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Preface 



This piibfiratinn is a reference manual and contains the macro instructions that 
are used for the virtual storage access method (VSAM). It is intended for 
programmers who use VSAM macro instructions, access method services 
commands, or JCL to process data. 



Organization 



This publication contains the following major sections: 

• Chapter 1, "Macro Instruction Return Codes and Reason Codes," contains 
return codes for macros used to open and close data sets, manage control 
blocks, and issue data management requests. 

• Chapter 2, **VSAM Macro Formats and Examples," describes the syntax of 
each macro and includes coded examples. 

• Appendix A, "Format of Macros," sununarizes, for ease of reference, the 
format of the macros used to communicate with VSAM. 

• Appendix S, "list, Ejtscutc, and^lenar^e F^enns of Macros," explains how 
to code reentrant programs with the macros that generate, modify, test, and 
display control blocks at execution. 

• Appendix C, "Operand Notation," defines the terms used to describe the 
operand notation used in the macros that generate, modify, test, and display 
control blocks at program execution time. 

• Appendix D, "Building Parameter Lists,** describes the standard way to 
build parameter lists. 

• "Glossaiy of Terms and Abbreviations*' defines VSAM terms. 

• Index is a subject index to this publication. 
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Prerequisite Knowledge 



Readers of this publication are assumed to have a programming background that 
includes: 

• VSAM data management 

• Catalog administration 

• Job control language 



Required Publications 

You should be familiar with the information presented in the following 
publications: 

♦ MVS/Extended Architecture Catalog Administration Guide, GC26-4138, 
describes the administration of tasks for catalogs and how to use the access 
method services commands to manipulate catalogs, and the objects cataloged 
m them. 



MVS/ Extended Architecture Data Facility Product Version 2: Customization, 
GC26-4267, contains consolidated customization information for the DFP 
library. 

M VS I Extended Architecture JCL Use/s Guide, GC28- 1 35 1 , and 

MVS/ Extended Architecture JCL Reference, GC28-1352, describes the JCL 

parameters referred to in this publication and describes dynamic allocation. 

MVS I Extended Architecture Message Library: System Messages, Volumes 1 
and 2, GC2S-1376 and GC28-1377, provides a complete listing of the 
messages issued by VSAM. 

M VS/ Extended Architecture VSAM Administration Guide, GC26-41 51, 
describes how to use VSAM. 



MVS/ Extended Architecture VSAM Logic, LY26-3970, describes the internal 
logic of VSAM. 



Related Publications 

Within the text, references are made to the publications listed in the table below: 
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Short Title 


Publication Title 


Order Number 


Access Method 

Services 

Reference 


MVS/Extended Architecture 
Integrated Catalog 
Administration: Access Method 
Services Reference 

MVSfExtended Architecture 
VSAM Catalog 

Administration: Access Method 
Services Reference 


GC26-4135 
GC26-4136 


Catalog 

Administration 

Guide 


MVS/ Extended Architecture 
Catalog Administration Guide 


GC26-4138 


Checkpoint/ 
Restart User's 
Guide 


MVS /Extended Architecture 
Checkpoint /Restart User's 

Guide 


GC26-4139 


Data Facility 

Product: 

Customization 


MVS /Extended Architectwe 
Data Facility Product Version 
2: Customization 


GC26-4267 


Data 

Administration: 
Macro 
insiruciiijn 
Reference 


MVS /Extended Architecture 
Data Administration: Macro 
Instruction Reference 


GC26-4141 


Data 

A Mac — IPQ7 


MVS /Extended Arc/utecture 


LYB8.1191 


Data 

Areas -JES3 


MVS/ Extended Architecture 
Data Areas -J ES 3 


LYB8-1195 


Data Facility 
Product: Master 
Index 


MVS/ Extended Architecture 
Data Facility Product Version 
2: Master Index 


GC26-4146 


Data Facility 
Product: 
Planning Guide 


MVS/ Extended Architecture 
Data Facility Product Version 
2: Planning Guide 


GC26-4147 


£)ebugg^lg 
Handbook 


MVS/ Extended Architecture 
System Programming Library: 
Debugging Handbook, 
Volumes 1 through 5 


LC28-1164' 
LC28-1165 
LC28-1166 
LC28-1167 
LC28.1168 


Introduction to 
the IBM 3850 
Mass Storage 
System 


Introduction to the IBM 3850 
Mass Storage System (MSS) 


GA32-0028 


JCL User's 
Guide 


MVS/Extended Architecture 
JCL User's Guide 


GC28-1351 


JCL Reference 


MVS /Extended Ardutecture 
JCL Reference 


GC28-1352 



Note: 



All five volumes may be ordered under one order number, LBOF-1015. 
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Short Title 


Publication Title 


Order Number 


OS/VS Mass 
Storage System 
Services: 
Reference 
Information 


OS/ VS Mass Storage System 
(MSS) Services: Reference 
Information 


GC35-0017 


RACF General 

Information 

Manual 


OS/ VS2 MVS Resource Access 
Control Facility (RA CF): 
General Information Manual 


GC28-0722 


Supervisor 
Services and 
Macro 
Instructions 


MVS/ Extended Architecture 
System Programming Library: 
Supervisor Services and Macro 
Instructions 


GC28-li54 


System Messages 


MVS/ Extended Architecture 
Message Library: System 
Messages, Volumes 1 and 2 


GC28-1376 
and 

GC28-1377 


Svstem 
Modifications 


M VS / Extended A rchitecture 
System Programming Library: 

System Modifications 


GC28-1152 


TSO Command 

language 

Reference 


OS/VS 2 TSO Command 
Language Reference with 
MVS/Extended Architecture 

supplement 


GC28-()646 
SD23-()259 


TSO Terminal 
User's Guide 


MVS/ Extended Architecture 
TSO Terminal User^s Guide 


GC28-1274 


VSAM 

Administration 
Guide 


MVS! Extended Architecture 
VSAM Administration Guide 


GC26-4151 


VSAM Logic 


MVS/ Extended Architecture 
VSAM Logic 


LY26-3970 


31-Bit 
Addressing 


MVS/ Extended Architecture 
System Programming Library: 
3 1 -Bit Addressing 


GC28.1158 



Notational Conventions 

A uniform system of notation describes the format of VSAM macro instructions. 
This notation is not part of the language; it merely provides a basis for describing 
the structure of the macros. 

The macro format illustrations in this book use the following conventions: 

• Brackets [ ) indicate optional parameters. 

• Braces ( } indicate a choice of entry; unless a default is indicated, you must 
choose one of the entries. 

• Items separated by a vertical bar (|) represent alternative items. No more 
than one of the items may be selected. 
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An ellipsis (...) indicates that multiple entries of the type immediately 
preceding the ellipsis are allowed. 

Other punctuation (parentheses, commas, etc.) must be entered as shown. 

BOLDFACE type indicates the exact characters to be entered. Such items 
must be entered exactly as illustrated (in uppercase, ci^pt in TSO). 

Italics type specifics fields to be supplied by the user. 

BOLDFACE^DERSCORED type indicates a default option. If the 
parameter is omitted, the underscored boldface value is assumed. 

A ' ' in the macro format indicates that a blank (an empty space) must be 
present before the next parameter. 
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Summary of Changes 



I Release 3.0, June 1987 



I New Programming Support 

I • A new parameter, MODE - 24131, has been added to the BLDVRP, 
I CLOSE, DLVRP and OPEN macros. 

I • A new parameter, RMODE31 = (ALL|BUFF|CB|NONE), has been added to 
I the ACB, BLDVRP, GENCB and MODCB macros. This new parameter 

I replaces the MACRF = AMODE31 subparamctcr in the ACB, 

I GENCB-ACB, and MODCB-ACB macros and the LOC parameter in the 

I BLDVRP and GENCB-RPL macros. 

I • A new specification, DATAjlNDEX, has been added to the TYPE parameter 
I in the BLDVRP macro. 

J A «ew op^n,XDS, lias be^ added lo the TESTCB-ACB macro. 

I • The parameter LOC » BELOWjANY has been added to the GENCB macro. 

I ♦ The BLDVRP, CLOSE, DLVRP, and OPEN parameter lists, the ACB, and 
I other control blocks and I/O buffers may now reside above or below 16 

i megabytes. 

I • New codes have been added to the logical error reason codes in the feedback 
I field of the request parameter list. 

I • New codes have been added to the return codes from BLDVRP and some 
i existing code descriptions have been changed. 

I • Some code descriptions have been changpd in the open reason codes in the 
i error field of the access method control block. 



Summary of Changes IX 



I Service Changes 

I Information has been added to reflect technical service changes. 

I Version 2 Publications 

I The tables containing the macro operand expressions in Appendix C, "Operand 

I Notation" have been deleted. 

Release 2.0, June 1986 

Service Changes 

Information has been added to reflect technical service changes. 

Version 2 Publications 

The prdace. has* been updated to include cuoder numbers. loc Veirsioa 2, 

Release 1.0, April 1985 

A new parameter, ACTION = REFRESH, has been added to the VERIFY 
macro. 

A new parameter, lOPID, has been added to the EXLST macro. This parameter 
permits termination of existing I/O and prevention of new I/O. 
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Chapter 1. Macro Instruction Return Codes and Reason Codes 



This chapter describes the return codes and reason codes generated by the macro 
instructions used to open and close a data set, manage VSAM control blocks, 
and issue data processing requests. 

VSAM sets the return codes in register 15. These return codes are paired with 
reason codes set in the access method control block (ACB) and the request 
parameter list (RPL). Reason codes set in the ACB indicate open or close errors. 
Reason codes set in the RPL indicate record management errors. 

This manual lists return codes and reason codes in decimal and hexadecimal 
values. The decimal value is shown first, followed by the hexadecimal value in 
parentheses. Format descriptions and examples of each macro are shown in 
Chapter 2, "VSAM Macro Formats and Examples" on page 33. 



When your program receives control after issuing an OPEN macro, the retum 
code in register 15 indicates whether all of the VSAM data sets were opened 
successfully: 



Return Codes and Reason 



Codes from OPEN 



Return 
Code 



Condition 



0(0) 



All data sets were opened successfully. 



4(4) 



All data sets were opened successfully, but one or more warning 
messages were issued (reason codes less than X'80'). 



8(8) 



At least one data set (VSAM or non-VSAM) was not opened 
successfully; the access method control block was restored to the 
contents it had before OPEN was issued; or, if the data set was 
already open, the access method control block remains open and 
usable and is not changed. 



12(C) 



A non-VSAM data set was not opened successfully when a 
non-VSAM and a VSAM data set were being opened at the same 
time; the non-VSAM data control block was not restored to the 
contents it had before OPEN was issued (and the data set cannot be 
opened without restoring the control block). 
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If register 15 contains a nonzero letum code, you can use the SHOWCB macro 
to display the corresponding reason code. The SHOWCB macro displays the 
error field in each access method control block specified by the OPEN macro. 
(Sec "SHOWCB Macro (Display Fields of an Access Method Control Block)" 
on page 133.) Figure 1 lists the reason codes that may appear in this error field. 
VSAM also writes a message to the operator console and to the progranuncr's 
listing to explain the error further. For a listing of VSAM messages, see System 
Messages. 



Reason 
Code 



Condition 



0(0) One of the following conditions exists: 

• VSAM is processing the access method control block for some 
other request. 

• The access method control block address is invalid. 

76(4C) Warning message: The interrupt recognition flag (IRF) was detected 
for a data set opened for input processing. 

92(5C) Warning message: Inconsistent use of CBUF processing. Sharing 
- qptions. diffex between index and'data^compcments^ 

96(60) Warning message: An unusable data set was opened for input. 

100(64) Warning message: OPEN encountered an empty alternate index that 
is part of an upgrade set. 

104(68) Warning message: The time stamp of the volume on which a data set 
is stored docsn t match the system time stamp in the data set's catalog 
record; this indicates that extent information in the catalog record 
may not agree with the extents indicated in the volume's VTOC. 

108(6C) Warning message: The time stamps of a data component and an 

index component do not match; this indicates that cither the data or 
the index has been updated separately from the other. 

1 16(74) Warning message: The data set was not properly closed and either 
OPEN'S implicit verify was unsuccessful or the user specified that 
OPEN'S implicit verify should not be executed. 

A previous VSAM program may have abnormally terminated. Data 
may be lost if processing continues; the access method services 
VERIFY command may be used to cause the data set to be properly 
closed. For a description of the VERIFY command, see Access 
Method Services Reference. In a cross-system shared DASD 
environment, a return code of 1 16 can have two meanings: (1) the 
data set was not property closed, or (2) the data set is opened for 
output on another processor. 

1 18(76) Warning message: The data set was not properly closed but OPEN's 
implicit verify was successfully executed. 

Figure t (Part 1 of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Reason 

Code Condition 

128(80) DD statement for this access method control block is missing or 
invalid. 



132(84) One of the following errors occurred: 

• Not enough storage was available for work areas. 

• The required volume could not be mounted. 

• An uncorrectable I/O error occurred while VSAM was reading 
the job file control block (JFCB). 

• The format- 1 DSCB or the catalog cluster record is invalid. 

• The user-supplied catalog name does not match the name on the 
entry. 

• The user is not authorized to open the catalog as a catalog. 

136(88) Not cnougih virtual storage space is available in your program's 
address space for work areas, control blocks, or buffers. 

140(8C) The catalog indicates this data set has an invalid physical record size. 

144(90) An uncorrectable I/O error occurred while VSAM was reading or 
writing a catalog record. 

145(91) An uncorrectable error occurred in the VSAM volume data set 
(WDS). 

148(94) No record for the data set to be opened was found in the available 
catalog(s), or an unidentified error occurred while VSAM was 
searching the catalog. For the catalog return code, see system 
message IDC3009I in System Messages. 



152(98) Authorization checking has failed for the following reasons: 

1. The password specified in the access method control block for a 
specified level of access doesn't match the password in the catalog 
for that level of access. 



2. RACF failure. For the catalog return code, see system message 
IDC3009I in System Messages. 

160(A0) The operands specified in the ACB or GENCB macro are 

inconsistent cither with each other or with the information in the 
catalog record. 

One of these conditions has been detected: 



• For option ACBRST 

- Path processing 

- LSRIGSR 

• For option ACBICI 

- LSRIGSR 

- KSDS 



Figure 1 (Part 2 of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Reason 
Code 



Condition 



— Path processing 

— Sequence set with data 

— Replicated index 

— Blocksize not equal to CI size 

• For option ACBUBF 

— LSRjGSR 

— ACBCNV not specified 

— ACBKEY specified 

— ACBADR specified 

• For option ACBSDS 

— LSRjGSR 

— Path processing 

— Upgrade processing 

• For option ACBCBIC 

— LSRIGSR 

— ACBICI not specified 

• For miscellaneous options 

— Bufferspace specified and the amount is too small to process 
the data s£i 

— Volume not mounted 

— Trying to open an empty data set for input 



164(A4) An uncorrectable I/O error occurred while VSAM was reading the 
volume label. 



168(A8) The data set was not available for the type of processing you 

specified, or an attempt was made to open a reusable data set with the 
reset option while another user had the data set open. The data set 
may have the INHIBIT attribute specified. 

The data set cannot be opened for CBUF processing because it was 
already opened for non-CBUF processing. Or the data set has 
conflicting CBUF attributes for the data and index components of the 
ACE. 

176(30) An error occurred while VSAM was attempting to fix a page of 
virtual storage in real storage. 

180(34) A VSAM catalog specified in JCL either does not exist or is not 

open, and no recoil for the data set to be opened was found in any 
other catalog. 

184(38) An uncorrectable I/O error occurred while VSAM was completing an 
I/O request. 

188(BC) The data set indicated by the access method control block is not of 
the type that may be specified by an access method control block. 

192(C0) An unusable data set was opened for output. 



Figure 1 (Part 3 of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Reason 
Code 



Condition 



193(C1) The interrupt recognition flag (IRF) was detected for a data set 
opened for output processing. 

196(04) Access to data was requested via an empty path. 

200(C8) The Format-4 DSCB indicates that the volume is unusable. There 
was an error in CONVER TV to convert the volume from either real 
to virtual or virtual to real. 

204(CC) The ACB MACRF specification is GSR and caller is not operating in 
supervisor protect key 0 to 7, or ACB MACRF specification is CBIC 
(Control Blocks in Common) and caller is not operating in supervisor 
state with protect key 0 to 7. 

205(CD) The ACBCATX option or VSAM volume data set OPEN was 
specified and the calling program was not authorized. 

208(D0) The ACB MACRF specification is GSR and caller is using an 
OS/VSl system. 

212(D4) The ACB MACRF specification is GSR or LSR and the data set 
requires load mode processing. 

216(D8) The ACB MACRF specification is GSR or LSR and the key length 
of the data set exceeds the maximum key length specified in 
BLDVRP. 

220(DC) The ACB MACRF specification is GSR or LSR and the data set's 
control interval size exceeds the size of the largest buffer specified in 
BLDVRP. 

224(E0) Improved control interval processing is specified and the data set 
requires load mode processing. 

228(E4) The ACB MACRF specification is GSR or LSR and the VSAM 
shared resource table (VSRT) does not exist (no buffer pool is 
available). 

^2(E8) Reset was specified for a nonreusable data set and the data set is not 
empty. 

236(EC) A permanent staging error occurred in MSS (ACQUIRE). 

240(F0) Format-4 DSCB and volume timestamp verification failed during 
volume moimt processing for output processing. 

244(F4) like volume containing the catalog recovery area was not mounted 
and not verified for output processing. 

Figure 1 (Part 4 of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Return Codes from CLOSE 



When your program receives control after it has issued a CLOSE macio» a return 
code in register 15 indicates whether all the VSAM data sets were closed 
successfully: 

Return 

Code Condition 

0(0) All data sets were closed successfully. 

4(4) At least one data set (VSAM or non-VSAM) was not closed 
successfully. 

If register 15 contains 4, you can use SIIOWCB to display the ERROR field in 
each access method control block to find out whether a VSAM data set wasn't 
closed successfully and why not. (See "StIOVVCB Macro (Display Fields of an 
Access Method Control Block)'* on page 133.) Figure 2 gives the reason codes 
that the ERROR field may contain following CLOSE. In addition to these 
reason codes, VSAM writes a message to the operator's console and the 
programmer's listing to further explain the error. For a listing of these messages, 
see System Messages. 



Return 

Code Condition 

0(0) No error (set when re^ster 15 contains 0)^ 

4(4) The data set indicated by the access method control block is already 
closed. 

129(81) TCLOSE was issued against a media manager's structure. 

132(84) An uncorrectable I/O error occuned while VSAM was reading the 
job file control block (JFCB). 

136(88) Not enough virtual storage was available in your program's address 
space for a work area for CLOSE. 

144(90) An uncorrectable I/O error occurred while VSAM was reading or 
writing a catalog record. 

145(91) An uncorrectable error occurred in the VSAM volume data set 
(WDS). 

148(94) An unidentified error occurred while VSAM was searching the 
catalog. 

Figure 2 (Part 1 of 2). CLOSE Reason Codes in the KKROR Field of the Access 
Method Control Block 
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Return 

Code Condition 

184(B8) An uncorrectable I/O error occurred while VSAM was completing 
outstanding I/O requests. 

236(EC) A permanent destaging error occurred in MSS (RELINQUISH). 
With temporary CLOSE, a destag^ig error or a sta^g error 
(ACQUIRE) occurred. 

Figure 2 (Part 2 of 2). CLOSE Reason Codes in the ERROR Field of the Access 
Method Control Block 



OPEN/CLOSE Message Area for Multiple Reason or Warning 
Messages 

During the execution of an OPEN, CLOSE, or TYPE'= T option of CLOSE, 
more than one error condition may be detected. However, the ACB error flag 
field can only accommodate one warning or error condition. In order to receive 
muhiple error or warning conditions, you may specify an optional message area. 
VSAM will accumulate error messages from an OPEN, CLOSE, or TYPE = T 
option in this message area. 

Multiple messages will be supplied when you specify nonzero values in the 
MAREA and MLEN parameters of the ACB. If MAREA or MLEN is not 
spedfled or is zero, no error or warning information is stored into the message 
area. The ACB error flag field is then the only indication for errors or warnings. 
If MAI^EA and MLEN are ^pecffied and^themficssage tureais too small tt> 
accommodate all messages, the last incoming messages are dropped. However, 
you will be given an indication of the number of warnings and me sages that 
occurred. 

The message area provided by VSAM is subdivided into two parts: 

• The message area header 

• The message list 

Message Area Header 

The message area header contains statistical, pointer, and general information. Its 
contents are unrelated to the individual messages. The format of the message 
area header is shown in Figure 3 on page 8. 
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Byte O Flag Byte 

bit 0—1 Full message area header has 
been stored. 

bit 0 » 0 Only flag byte of message area 
header has been stored. 
(Implies that no messages 
have been stored.) 

bits 1-7 Reserved (set to binary zeros) 

Bytes 1-2 Length of message area header (includes flag byte 

and length byte) 

Byte 3 Request type code: 

X'Or OPEN 

X'Or CLOSE 

X'Or TCLOSE 

E34es 4tII ddaamc used.&r ACB. 

Bytes 12-13 Total number of messages (error or warning 

conditions) issued by OPEN/CLOSE/ TCLOSE 

Bytes 14- 15 Number of messages stored by OPEN/CLOSE/TCLOSE 
into message area 

Bytes 16- 19 Address of message list, for example, of first 
message in message area 

Figure 3. Format of the Message Area Header 



The function of the ACB error flag field remains unchanged whether or not this 
optional message area is specified. At the end of an OPEN, CLOSE, or 
TCLOSE, this field contains either X * 00 * (indicating no error or warning 
condition occurred) or a nonzero code. The ACB error flag byte stores the 
nonzero OPEN/CLOSE/TCl>OSE reason code corresponding to the error or 
warning condition that occurred with the highest severity. 

Message area header information is only stored when a warning or error 
condition is detected; that is, when the ACB error flag field is set to a nonzero 
value. The header information consists of the flag byte only if the message area 
length (MLEN) is not large enough to accommodate the fuU message area 
header. In this case, bit 0 of the flag byte will be zero. Before accessing the 
message header information (bytes 1 through 19), test byte 0 to see if more 
information is stored. If MLEN~0, no header information is stored, not even 
the flag byte. If the full message area header is stored, bytes 1 and 2 contain its 
actual length. Your program should be sensitive to this length when interrogating 
the message area header. 



S 
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The message list contains individual messages corresponding to detected warning 
or error conditions. Bytes 16 through 19 of the message area header point to the 
location of the message list within the message area. If the message area header is 
not stored completely (bit 0 of byte 0 is 0), the location of the message list is not 
provided. Within the message list, individual messages are stored as a contiguous 
string of variable-length records. Byles 14 and 15 of the message area header 
contain the number of messages stored. Check for a nonzero stored message 
count before investigating the message list. However, messages may not be 
stored even if the ACB error flag byte contains a nonzero value and the message 
area header bit 0 of byte 0 is 1. For example, no messages will be stored if 
MLBN is not large enough to allow at least one message to be stored. 

The format of the individual messages is given in Figure 4. 



Bytes 0-1 Length of message including these two bytes. 

Byte 2 ACB error flag code corresp>onding to the error or warning 
condition represented by this message. 

Byte 3 Function type code: 

Specifies which dsname, if any, is stored in bytes 4 through 47 of 
the message. 

X'OO' no dsname stored. Bytes 4-47 of the message contain 
binary zeros, llie error warning condition is not clearly 
related to a component, or VSAM was unable to identify 
or obtain the cluster name of the component in error. 
This code is used only if the ddname of the ACB does not 
identify a valid DD statement, or VSAM was unable to 
obtain the dsnsne contained in the OD statement. 

X'Or dsname contained in DD statement is stored. The error 
or warning condition is not clearly related to a 
component, or VSAM was unable to identify or obtain 
the cluster name of the component in error. 

X'02' dsname (cluster name) of base cluster stored. Error 
occurred during OPEN/CLOSE/TCLOSE for base 
cluster. 

X'03' dsname (cluster name) of alternate index component 

stored. Error occurred during OPEN/CLOSE/I CLOSE 
for altemate index component. 

X'04' dsname (cluster name) of member of upgrade set stored. 
Error occurred during OPEN/CLOSE/TCLOSH for this 
member of the upgrade set. 

Bytes 4-47 Binary zeros (function type code - X'OO') or a dsname as described 
by byte 3. 

Figure 4. Format of Individual Messages in Message List 
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Bytes 0 and 1 of each mcssa^ specify its actual length. Because messages vary in 
length, you will need to know the actual length of each message in order to do 
your processing. 

Byte 2 of the message contains the ACB error flag code; it does not indicate that 
a dsname has been stored. Depending on the condition that raised the ACB 
error flag code, either no dsname or different types of dsnames (DD, base cluster, 
alternate index, or upgrade set member) may be stored. (The same condition 
may be detected both when opening the base cluster and when opening a 
member of the upgrade set. For example, an I/O error may occur when trying to 
obtain the dsname for the component in error.) Bytes 4 through 47 of the 
message can contain a dsname, but do not specify its type. Only byte 3 of the 
message specifies whether a dsname has been stored and, if so, its type. 



i Control Block Manipulation Macro Return Codes and Reason Codes 

The GENCB, MODCB, SIIOWCB, and TKSTCB macros are executable (unUke 
the ACB, EXLST, and RPL macros). They cause control to be ^ven to VSAM 
to perform the indicated task. VSAM indicates if the task was completed by a 
return code in register 15: 

Return 

Code Condition 

0(0) Task completed. 

^ 4(4) Task not completed. 

8(S) An attempt was made to use the execute form of a macro to modify a 
keyword that isn't in the parameter Ust. (See Appendix B, "List, 
Execute, and Generate Forms of Macros" on page 171.) 

An error can occur because you specified the operands incorrectly or, if you 
constructed a parameter list yourself, because the parameter list was coded 
incorrectly. See Appendix D, "Building Parameter Lists" on page 183, for an 
explanation of how to construct parameter lists for GENCB, MODCB, 
SIIOWCB. and TESTCB. 

When Gegister-l'5^fitatn»4Mcgister (^neentetos^ ^sason code;, indicating, whyt^ 
>£SA!tftMli!fr'tnperfo^ you construct the parameter list, register 0 

can contain reason codes 1, 2, 3, 10, 14, 20, and 21. Figure 5 on pa^ 1 1 
describes each reason code that can be returned in register 0. 
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Reason 
Code 



Applicable 
Macros' 



Reason VSAM Couldn't Perform the Task 




1(1) G,M,S,T The request type (generate, modify, show, or test) is 
invalid. 

2(2) G,M,S,T The block type (access method control block, exit list, or 
request parameter list) is invalid. 

3(3) G,M,S,T One of the keyword codes in the parameter list is invalid. 

4(4) M,S,T The block at the address indicated is not of the type you 
indicated (access method control block, exit list, or request 
parameter list). 

Access method control block fields were to be shown or 
tested, but the data set is not open or it is not a VSAiM 
data set. 

Access method control block information about an index 
was to be shown or tested, but no index was opened with 
the data set. 

7(7) M,S An exit list was to be modified, but the list was not large 

enough to contain the new entry; or an exit was to be 
modified or shown but the speoTicd exit wasn't in the exit 
list. (With TliSTCB, if the specified exit address isn't 
present, you get an unequal condition when you test for 
it.) 

8(8) G There isn't enough virtual storage in your program's 

address space to generate the access method control 
block(s), exit list(s), or request parameter list(s) and no 
work area outside your address space was specified. 

9(4) <J ,S The worft affca specified was too small for generation <5r 

display of the indicated control block or fields. 

10(A) G,M With GENCB, exit list control block type was specified 

and you specified an exit without without giving an 
address. With MODCB, exit list control block type was 
specified and you specified an exit without giving an 
address; in this case, either active or inactive must be 
specified, but load cannot be specified. 

1 1(B) M Either (1) a request parameter list was to be modified, but 

the request parameter list defines an asynchronous request 
that is active (that is, no CHECK or ENDREQ has been 
issued on the request) and thus cannot be modified; or (2) 
MODCB is already issued for the control block, but 
hasn't yet completed. 



Figure 5 (Part I of 2). GENCB, MODCB, SHOWCB, and TESTCB Reason Codes 
Returned in Register 0 
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Reason Applicable 
Code Macros* 



Reason VSAM Couldn't Perform the Task 



12(C) M 

13(D) M 

14(E) GMJ 

15(F) G,S 

16(10) G,M,S,T 

19(13V MXT 



20(14) S 
21(15) S.T 
22(16) S 



An access method control block was to be modified, but 
the data set identified by the access method control block 
is open and thus cannot be modified. 

An exit list was to be modified, and you attempted to 
activate an exit without providing a new exit address. 
Because the exit list indicated does not contain an address 
for that exit, your request cannot be honored. 

One of the option codes (for MACRF, ATRB, or 
OPTCD) has an invalid combination of option codes 
specified (for example, OPTCD = (ADR, SKP)). 

The woric area specified did not begin on a fuUword 
boundary. 

A VTAM keyword or subparameter was specified but the 
AM = VTAM parameter was not specified. AM = VTAM 
must be specified in order to process a VTAM version of 
the control block. 

A. keyword was> specified wluch refers, to a field b&yond 
the length of the control block located at the address 
indicated. (For example, a VTAM keyword was specified, 
but the control block pointed to was a shorter, 
non-VTAM block.) 

Keywords were specified which apply only if 
MACRF = LSRorGSR. 

The block to be displayed or tested does not exist because 
the data set is a dummy data set. 

AM = VTAM was specified and the RPL FIELDS 
parameter conflicts with the RPLNIB bit status. Either 
RPLFIELDS = NIB was specified and the RPLNIB was 
off, or RPL FIELDS - ARG was specified and the 
RPLNIB bit was on. 



Figure 5 (Part 2 of 2). GENCB, MODCB, SIIOWCB, and 1 ESTCB Reason Codes 
Returned in Register 0 

Note to Figure 5: 

> G«GENCB, M«MODCB, S«SIIOWCB,T*TESTCB 



MVS/XA VSAM Administration: Macro Instruction Reference 



Record Management Return Codes and Reason Codes 



The following record management macros give return codes and reason codes in 
the feedback area of the RPL: GET, PUT. POINT. ERASE. CHECK, 
ENDREQ, GETIX, PUTIX, ACQRANGE, CNVTAD. MNTACQ, 
MRKBFR, SCHBFR, and WRTBFR. 

I The feedback word in the RPL consists of four bytes: 

I Byte Description 

I 1 Problem determination function (PDF) code. This code is used to locate 
i the point in VSAM record management at which a logical error 

I condition is recognbed. A description of the returned PDF code is 

I located in the IDARMRCD macro. 

I 2 RPL return code. This code is returned in register 15. 

i 3 Component code. This code specifies the component being processed 
I when the error occurred. 

I 4 Reason code. This code, when paired with the return code in byte 2, 
I specifies the actual reason for cither a successful completion or an error. 

I Bytes 2 through 4 make up the RPL feedback area. An explanation of the codes 

I that app>ear in these three bytes follows. 

I Bytes 3 and 4 make up the RPL condition code. An explanation of this code 

I also follows. 

I The field name of each byte appears within parentheses in the following figure. 



RPL Feedback Word (4 t^ytes) 

' RPL Feedback Area C3 bytes) 



RPL Condition Code (2 bytes) 







PDF Code 
(RPLFUNCD) 


Return Code 
(RPLRTNCD) 


Component Code 
(RPLCMPON) 


Reason Code 
(RPLERRCD) 



i For more information on the RPL feedback word, see VSAM Logic. 

Return Codes (RPLRTNCD) 

The meaning of the return code depends on whether processing is asynchronous 
or synchronous. 
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Asynchronous Request 



After you issue an asyachionous request for access to a data set, VSAM issues a 
return code in register 15 to indicate whether the request was accepted, as follows: 



Return Code 

(RPLRTNCD) Condition 



0(0) Request was accepted. 

4(4) Request was not accepted because the request parameter list 

indicated by the request (RPL- address) was active for another 
request. 

If the asynchronous request was accepted, issue a CHECK after doing your other 
processing so VSAM can indicate in register 15 whether the request was 
completed successfully, set a return code in the feedback area, and exit to any 
appropriate e)dt routine. If the request was not accepted, you should either wait 
until the other request is complete (for example, by issuing a CHECK on the 
request parameter list) or terminate the other request (using ENDRCQ). Then 
you can reissue the rejected request. 

Syncbroaoii» Rfi({iKaU. 

After a synchronous request, or a CHECK or ENDREQ macro, the return code 
in register 15 indicates whether the request was completed successfully, as follows: 

Return Code 

(RPLRllSCD) Condition 



0(0) Request completed successfully. 

4(4) Request was not accepted because the request parameter list 

indicated by the request (R PL address) was active for another 
request. 

8(8) Logical error; specific error is indicated in the feedback area in 

theRPL. 

12(C) Physical error; specific error is indicated in the feedback area in 

the RPL. 



Component Codes (RPLCMPON) 

When a logical or physical error occurs, VSAM uses the component code field of 
the RPL to identify the component being processed when the error occurred and 
indicates whether the alternate index upgrade set is correct following the request 
that failed. The component code can be displayed and tested by using the 
SHOWCB and TESTCB macros. The codes and their meanings are given in 
Figure 6 on page 15. 



14 
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Note: The component code (byte 3 of the RPL feedback word) and the reason 
code (byte 4 of the RPL feedback word) make up the 2-byte RPL condition 
code. 



For more information on the RPL feedback word see VSAM Logic. 



Component Code 
(RPLCMPON) 


What Was Iking 
Processed 


Upgrade Set Status 


0(0) 


Base cluster 


Correct 


1(1) 


Base cluster 


May be incorrect 


2(2) 


Alternate index 


Correct 


3(3) 


Alternate index 


May be incorrect 


4(4) 


Upgrade set 


Correct 


5(5) 


Upgrade set 


May be incorrect 



Figure 6. Component Codes Provided in the KI*L 



i Reason Codes (RPLERRCD) 

The 0, 8, and 12 return codes in register 15 are paired with reason codes in the 
feedback area of the request parameter list. 

The reason codes in the feedback area of the request parameter list can be 
examined with the SHOWCB or TESTCB macro. You may code your 
examination routine inuncdiately following the request macro. Logical errors, 
physical ^errors, tmd rcadiing the end of the data set afi cause VSAM to ^xit to 
the appropriate exit routine, if you provide one. 

Coordinate error checking in your program with your error-analysb exit routines. 
If they terminate the program, for instance, you would not need to code a check 
for an error after a request. But if a routine returns to VSAM to continue 
processing, you should check register 15 after a request to determine whether 
there was an error. Even though the error was handled by an exit routine, you 
may want to modify processing because of the error. 

Reason Code (Successful Request) 

When the request is completed, register 15 is set to indicate the status of the 
request. A reason code of 0 indicates successful completion. Nonzero codes are 
set for a variety of other reasons. Figure 7 on page 16 lists these codes and their 
meanings. 
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Reason Code 

(RPLERRCD) 

When Register 

15" 0(0) Condition 

0(0) Request completed successfully. 

4(4) Request completed successfully. For retrieval, VSAM mounted 

another volume to locate the record; for storage, VSAM allocated 
additional space or mounted another volume. 

8(8) For GET requests, indicates a duplicate alternate key exists 

(appUes only when accessing a data set using an alternate index 
that allows nonunique keys); for PUT requests, indicates that a 
duplicate key was created in an alternate index with the 
nonunique attribute. 



12(C) All buffers, except for the buffer just obtained, may have been 

modified and may need to be written; issuance of WRTBFR 
macro is suggested. 

16(10) The sequence-set record does not have enough space to allow it 

to address all of the control intervals in the control area that 
should contain the record. The record was written into a new 
c^u^Orol area. 



20(14) Data set is not on virtual DASD for 

CNVTAD/MNTACQ/ACQRANGE request. 

24( 18) Buffer found but not modified; no buffer writes performed. 

28(1 C) Control interval split indicator was detected during an addressed 

GET NUP request. 

32(20) Request deferred for a resource held by the terminated RPL is 

asynchronous and cannot be restarted by TERMRPL. 

36(24) Possible data set error condition was detected by TERMRPL: 

• The request was abnormally terminated in the middle of its 
I/O operation. 

• One of the data/index BUFCs of the string contains data that 
needs to be written (BUFCMW= ON) but it was invalidated 
by TERMRPL. 

40(28) Error in PLH data BUFC pointer was detected by TERMRPL. 

Figure 7. Successful Comptetion Reason Codes in the Feedback Area of the Request 
Parameter List 
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Reason Code (Logical Errors) 



If a logical error occurs and you have no LERAD routine (or the LERAD exit is 
inactive), VSAM returns control to your program following the last executed 
instruction. ("User-Written-Exit Routines" in Data Facility Product: 
Customization describes the LERAD routine.) The return code in register 1 5 
indicates a logical error (8), and the feedback area in the request parameter list 
contains a reason code identifying the error. Register 1 points to the request 
parameter list. 

Figure 8 gives the reason codes shown in the feedback area and explains their 
meanings. 



Reason Code 

(RPLERRCD) 

When Register 

15 8(8) Condition 

End of data set encountered (during sequential or 
skip sequential retrieval), or the search argument 
is greater than the high key of the data set. 
Either no EODAD routine is provided, or one is 
provided, returned to VSAM, and the processing 
program issued another GET. ("User-Written-Exit 
Routines" in VSAM Administration Guide describes 
the EODAD routine.) 

You attempted to store a record with a duplicate 
key, or there is a duplicate record for an 
alternate index with the unique key option. 

A key sequence check was performed and an error was 
detected in one of the following processing 
conditions: 

* Fot^ tey-scquenced data set 

— PUT sequential or skip-sequential processmg 

— GET sequential, single string input only 

— GET skip-sequential processing and the previous 
request is not a POINT 

• For a relative record data set 

— GET skip-sequential processing 

— PUT skip-sequential processing 

16(10) Record not foimd, or 

the RBA is not found in the buffer pool. 

Figure 8 (Part I of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 



4(4) 

12(C) 
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Reason Code 

(RPLERRCD) 

When Register 

15 » 8(8) Condition 

20(14) The RBA is found, but the buffer is under the exclusive control of 
another request. With this condition, it is possible to also have 
buffers invalidated. Or, the control interval is for a record already 
held in exclusive control by another requester. 

Note: If the RPL message area is correctly specified, the following 
information is returned: 

Offset Length Discussion 

0 4 Address of RPL in exclusive 
control 

4 1 Flag Byte: 

X ' 00 * - neither RPL is doing a 
control area split 

X * 01 ' - current RPL is attempting a 
con^l area spiii 

X * 02 * - other RPL is doing 
a control area spUt 

24(18) Record resides on a volume that can't be mounted. 

28(1 C) Data set cannot be extended because VSAM can't allocate 

additional direct access storage space. Either there is not enough 
space left to make the secondary allocation request or you 
attempted to increase the size of a data set while processing with 
SHAREOPTIONS«4 and DISP^SHR. 

32(20) You specified an RBA that doesn't give the address of any data 

record in the data set. 

36(24) Key ranges were specified for the data set when it was defined, but 
no range was speofied that includes the record to be inserted. 

40(28) Insufficient virtual storage in your address space to complete the 
request. 

44(2C) Work area not large enough for the data record or for the buffer 
(GET with 01»TCD = MVE). 

Figure 8 (Part 2 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 
(RPLERRCD) 
When Registcr 
15««8(8) Condition 

48(30) Invalid options, data set attributes, or processing conditions 
specified for TERMRPL request: 



• CNV processing 

• The specified RPL is asynchronous 

• Chained RPLs 

• Path processing 

• Shared resources (LSR/GSR) 

• Load mode 

• Relative record data set 

• Data set contains spanned records 

• User not in key 0 and supervisor state 

• End-of-volume in process (secondary allocation) 

52(34) The previous request was TERMRPL. 

64(40) There is insufficient storage available to dynamically add another 

string. Or, the maximum number of placeholders that may be 
allocated to the request has been allocated, and a placeholder is not 
available. 



68(44) You attempted to use a type of processing (output or control 

interval proces^g) that was not specified when the data set was 
opened. 

72(48) You made a keyed request for access to an cntry-sequenced data 
set, or you issued a GETIX or PUTIX to an entry-sequenced or 
relative record data set. 

76(4C) You issued an addressed or control interval PUT to add to a 

key-sequenced data set, or you issued a control interval PUT to a 
relative record data set. 

80(50) You issued an ERASE request in one of the following situations: 

• For access to an entry-sequenced data set. 

• For access to an cntiy-sequenced data set via a path. 

• With control interval access. 

84(54) You specified OPTCD = LOG in one of the following situations: 

• For a PUT request. 

• In a request parameter list in a diain of request parameter lists. 

• For UBF ]»ocessing. 



Figure 8 (Part 3 irf" ?>. Logical Error Reason Codes in tiie Feedbadi Area of the 
Request Parameter List 
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Reason Code 
(RPLERRCD) 
When Register 
15"S(8) Condition 



88({ 



92(5C) 
96(60) 
100(64) 
104(68) 



You issued a sequential GET request without having caused 
VSAM to be positioned for it, or you changed from addressed 
aca;ss to keyed access without causing VSAM to be (>ositioned for 
keyed-sequential retrieval; there was no positioning established for 
sequential PUT insert for a relative record data set, or you 
attempted an illegal switch between forward and backward 
processing. 

You issued a PUT for update or an ERASE without a previous 
GET for update, or a PUTIX without a previous GETIX. 

You attempted to change the prime key or key of reference while 
making an update. 

You attempted to change the length of a record while making an 
addressed update. 

The RPL options are either invalid or conflicting in one of the 
following, ways: 

• SKP was specified and either KEY was not specified or BVVD 
was specified. 

• BWD was specified for CNV processing. 

• FWD and LRD were specified. 

• Neither ADR, CNV, nor KEY was specified in the RPL. 

• BFRNO is invalid (less than 1 or greater than the number of 
buffers in the pool). 

• WRTBFR, MRKBFR, or SCHBFR was issued, but either 
TRANSID was greater than 31 or the shared resource option 
was not specified. 

• ICI processing was specified, but a request other than a GET 
or a PUT was issued. 

• MRKBFR MARK = OUT or MARK= RLS was issued but 
the RPL did not have a data buffer associated with it. 

• The RPL specified WAITX, but the ACB did not specify LSR 
or GSR. 



Figure 8 (Part 4 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter Lbt 
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Reason Code 

(RPLERRCD) 

When Register 

15 "8(8) Condition 

108(6C) RECLEN specified was larger than the maximum allowed, equal to 
0, or smaller than the sum of the length and the displacement of 
the key field; RECLEN was not equal to record (slot) size specified 
for a relative record data set. The automatic increase in the record 
size of an upgrade index for the base cluster may cause an incorrect 
RECLEN specification. 

1 12(70) KEYLEN specified was too large or equal to 0. 



1 16(74) During initial data set loading (that is, when records arc being 
stored in the data set the first time it's opened), GET, POINT, 
ERASE, direct PUT, skip-sequential PUT, or PUT with 
OPTCD= UPD is not allowed. For initial loading of a relative 
record data set, the request was other than a PUT insert. 

120(78) The request was operating under an incorrect TCB. For example, 
an end-of- volume call or a GETMAIN would have been necessary 
to complete the request, but the request was issued from a job step 
other than the one that opened the data set. The request can be 
resubmitted from the correct task, if the new request reestablishes 
positioning. 

124(7C) A request was cancelled for a user JRNAD exit. 

132(84) An attempt was made in locate mode to retrieve a spanned record. 

136(88) You attempted an addressed GET of a spanned record in a 
kcy-sequenccd data set. 

140(8C) The spanned record segment update number is inconsistent. 

144(90) Invalid pointer (no associated base record) in an alternate index. 

148(94) The maximum number of pointers in the alternate index has been 
exceeded. 



152(98) Not enough buffers are available to process your request (shared 
resources only). 

156(9C) An invalid control interval was detected during keyed processing, or 
an addressed GET UPD request failed because the control interval 
flag was on, or an invalid control interval or index record was 
detected. The RPL contains the invalid control interval's RBA. 



Figure 8 (Part 5 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Codie 

(RPLERRCD) 

When Register 

15 » 8(8) Condition 

160(A0) 



One or more candidates were found that have a modified buffer 
marked to be written. The buffer was left in write status with valid 
contents. With this condition, it is possible to have other buffers 
invalidated or found under exclusive control. 



164(A4) One of the following invalid options was specified for a 
CNVTAD/MNTACQ/ACQRANGE request: 

Generic key (GEN) 

Load mode 

Path processing 

User buffers (UBF) with LSR/GSR 
Key-sequenced data set, but not key processing (KEY) 
Entry-scqjjenced data set, but not address processing (ADR) 
Relative record data set, but not key processing (KEY) 
RPL is chained 

Key-sequenced data set has single-level imbedded index 

168(A8) One of the following user parameter list errors was detected for 
CNVTAD/MNTACQ/ACQRANGE request: 

No user parameter list is specified (RPLARG - 0) 

Argument count is zero for CNVTAD/MNTACQ request 

Ending argument is less than starting argument for 
ACQRANGE request 

Parameter list not on word boundary 

i72(AC) ACQUIRE error returned by SVC 126 for 
MNTACQ/ACQRANGE request. 

176(B0) Staging failure for MNTACQ/ACQRANGE request. 

180(B4) RBA/volumc error for MNTACQ/ACQRANGE request. 

(Required volume not mounted or specified RBA(s) not on 
mounted volume.) 



Figure 8 (Part 6 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 

(RPLERRCD) 

When Register 

15 = 8(8) Condition 

184(B8) Catalog errors returned from SVC 126 for CNVTAD request. 
188(BC) Storage for ACQUIRE ECBs (subpool 241) is not available. 
192(C0) Invalid relative record number. 

196(C4) You issued an addressed request to a relative record data set. 

200(C8) You attempted addressed or control interval access through a path. 

204(CC) PUT insert requests are not allowed in backward mode. 

208(D0) The user has issued an ENDREQ macro instruction against an 
RPL that has an outstanding WAIT against the ECB associated 
with the RPL. This can occur when an ENDREQ is issued from a 
STAE or ESTAE routine routine against an RPL that was started 
before the abend. No ENDREQ processing has been done. 

212(£>4) During control area split processing, a condition exists that prevents 
the spUt of the index record. Index control interval size may need 
to be increased. 

224(E0) MRKBFR OUT was issued for a buffer with invalid contents. 

228(E4) Caller in cross-memory mode is not in supervisor state or RPL of 
caller in SRB or cross-memory mode docs not specify SYN 
processing. 

232(E8) UPAD error; ECB was not posted by user in cross-memory mode. 

236(EC) Validity check error for SHAREOPTIONS 3 or 4. 

240(F0) For shared resources, one of the following is being performed: (a) 
an attempt is being made to obtain a buffer in exclusive control, (b) 
a buffer is being invalidated, or (c) the buffer use chain is changing. 
For more detailed feedback, reissue the request. 

244(F4) Register 14 stack size is not largp enough. 

248(F8) Register 14 return offset went negative. 

252(FC) Record mode processing is not allowed for a linear data set. 

253(FD) VERIFY is not a valid function for a linear data set. 

Figure 8 (Part 7 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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When the search argument you supply for a POINT or GET request is greater 
than the highest key in the data set, the reason code in the feedback area depends 
on the RPL's OPTGD values, as shovm in the table below: 



Request RPLs OPTCD 
Type Options 



Reason Code (RPLERRCD) 
When Register 15- S(8) 



Decimal Hexadecimal 



POINT GEN.KEQ 16 

POINT GEN.KGE 4 

POINT FKS,KEQ 16 

POINT FKS,KGE 4 

GET GEN.KEQ.DIR 16 

GET GEN.KGE.DIR 16 

GET FKS,KEQ,DIR 16 

GET FKS.KGE.DIR 16 

GET GEN,KEQ,SKP 16 

GET GEN,KGE,SKP 4 

GET FKS,KEQ,SKP 16 

GET FKS,KGE,SKP 4 



XMO* 

X'4' 

X'lO' 

X'4* 

XMO* 

XMO' 

XMO' 

X'lO' 

X*10' 

X'4' 

XMO' 

X'4' 



Positioning Following Lopcal E4Proc& 

VSAM is unable to maintain positioning after every lo^cal error. Whenever 
positioning is not maintained following an error request, you must reestablish it 
before processing resumes. 

Positioning may be in one of four states following a POINT or a direct request 
that encountered a lo^cal error 

Yes VSAM is positioned at the position in effect before the request in error 
was issued. 

No VSAM is not positioned, because no positioning was established at the 
time the requeit in error was issued. 

New VSAM is positioned at a new position. 

U VSAM is positioned at an unpredictable position. 

The following tabic shows which positioning state applies to each reason code 
listed for sequential, direct, and skip-sequential processing. **N/A** indicates that 
the reason code is not applicable to the type of processing indicated. Figure 9 on 
page 25 lists these codes and their meanings. 
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Reason Code 
(RPLERRCD) 
Sviicn Register 
15 = 8(8) 

Decimal Hexadecimal Sequential Direct Skip-Sequential 



4 


X 


'4' 


Yes 


N/A 


Yes 


8 


X 


•8*» 


Yes 


No 


New 


12 


X 


'C 


Yes 


N/A 


Yes 


16 


X 


'10' 


No 


No 


No 


20 


X 


'14* 


u 


No2 


No' 


24 


X 


'18' 


Yes 


No 


No 


28 


X 


' IC' 


Yes 


No 


Yes 


32 


X 


'20' 


No 


No 


N/A 


36 


X 


'24' 


Yes 


No 


New 


40 


X 


'28' 


Yes 


No 


No 


44 


X 


'2C' 


Yes 


New 


Yes 


64 


X 


'40' 


No 


No 


No 


68 


X 


'44' 


Yes 


Yes 


Yes 


72 


X 


'48' 


Yes 


Yes 


Yes 


76 


X' 


'4C' 


Yes 


Yes 


Yes 


80 


X' 


'50' 


Yes 


Yes 


Yes 


84 


X 


'54' 


Yes 


Yes 


Yes 


88 


X 


'58' 


Yes 


Yes 


Yes 


92 


X 


'5C' 


Yes 


Yes 


Yes 


96 


X' 


'60' 


Yes 


Yes 


Yes 


100 


X' 


'64' 


Yes 


Yes 


Yes 


104 


X 


'68' 


Yes 


New 


Yes 


108 


X 


6C' 


Yes 


New 


Yes 


112 


X' 


70' 


Yes 


Yes 


Yes 


116 


X' 


'74' 


Yes 


Yes 


Yfis 


120 


X' 


78' 


Yes 


No 


No 


124 


X 


7C' 


No 


No 


No 


132 


X' 


84' 


Yes 


New 


Yes 


136 


X' 


88' 


No 


No 


N/A 


140 


X' 


8C' 


Yes 


New 


Yes 


144 


X' 


90' 


Yes 


Yes 


Yes 


148 


X' 


94' 


Yes 


Yes 


Yes 


152 


X' 


98' 


Yes 


No 


No 


156 


X' 


9C' 


Yes 


No 


No 


160 


X' 


AO' 


N/A 


No 


N/A 


192 


X' 


CO' 


Yes 


Yes 


Yes 


196 


X' 


C4' 


Yes 


Yes 


Yes 



Figure 9 (Part I 2). Positioning States oT Reason Codes Listed for Sequential, 
Direct, and Skip-Sequential Processing 
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Reason Code 
(RPLERRCD) 
When Rcgbter 
15-8(8) 



Decimal 


Hexadecimal 


Sequential 


Direct 


Skip-Sequential 


200 


X*C8* 


Yes 


Yes 


Yes 


204 


X*CC* 


Yes 


Yes 


Yes 


208 


X*DO* 


Yes 


Yes 


Yes 


224 


X'EO' 


N/A 


No 


N/A 


228 


X*E4' 


No 


No 


No 


232 


X*E8* 


No 


No 


No 


236 


X*EC' 


No 


No 


No 


240 


X*FO* 


Yes 


Yes 


Yes 



* A subsequent GET SEQ will retrieve the duplicate record; however, a 
subsequent GET SKP for the same key will get a sequence error. In a 
relative record data set, a subsequent PUT SEQ positions to the next slot 
(whether the slot is empty or not). 

* PUT UPD, DIR or UPD, SKP retains positioning. The RPL contains an 
RBA that could not be obtained for exclusive control. 

Figure 9^ (Paarl 2 ^ 2)t Pos feiowmg St^gr of ReMoa^Cod^ Listed for Scqncntiat^ 
Direct, and Skip-Sequential Processing 



( 

Reason Code (Physical Errors) 

If a physical error occurs and you have no SYNAD routine (or the SYNAD exit 
is inactive), VSAM returns control to your program following the last executed 
instruction. The return code in register 15 indicates a physical error (12), and the 
feedback area in the request parameter list contains a reason code identifying the 
error; the RPL message area contains more details about the error. Register 1 
points to the request parameter list. The RBA field in the request parameter list 
gives the relative byte address of the control interval in which the physical error 
occurred. Figure 10 gives the reason codes in the feedback area and explains 
what each in^cates. 
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Reason Code 

(RPLERRCD) 

When Register 

15- ]2(0C) Condition 

4(4) Read error occurred for a data set. 

8(8) Read error occurred for ail index set. 

12(C) Read error occurred for a sequence set. 

16(10) Write error occurred for a data set. 

20(14) Write error occurred for an index set. 

24(18) Write error occurred for a sequence set. 

Figure 10. Physical Error Reason Codes in the Feedback Area of the Request 
Parameter List 



Figure 1 1 gives the format of a physical error message, llie format and some of 
the contents of the message are purposely similar to the format and contents of 
the SYNADAF message, which is described in Data Administration: Macro 
Instruction Reference. 



Field Bytes Lx»gth Discussion 

Message 0-1 2 Binary value of 128 

Length 

2-3 2 Unused (0) 

Message 4-3 2 B'mary value of 124 

Length - 4 (provided for compatibility 

with SYNADAF Message) 

6-7 2 Unused (0) 

Address of 8-11 4 The I/O buffer associated 

I/O Buffer with the data where 

the error occurred 

The rest of the message is in printable format 

Date 12-16 5 YYDDD (year and day) 

17 1 Comma (,) 

Time 18-25 8 HHMMSSTH (hour, minute, 

second, and tenths and 
hundr»iths of a second 

Figure II (Part I of 4). Physical Error Message Format 
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Field 



RBA 



Length Discussion 



Component 
TYPE 



Volume Serial 
Number 



Job Name 



Step Name 



Unit 



Device Type 



ddname 



Bytes 

26 1 ' Comma (,) 

27-34 8 Relative byte address of the 

record where 
the error occurred 

35 1 Comma (,) 

36-41 6 "DATA" or "INDEX" 

42 1 Comma (,) 

43-48 6 Volume serial number of the 

volume where 
the error occurred 

49 1 Comma (,) 

50-57 8 Name of the job where 

error occunred 

58 1 Comma (,) 

59-66 8 Name of the job step in 

which error occurred 

67 1 Comma (,) 

68-70 3 The unit, CUU (channel and 

unit), where 
the error occurred 

71 1 Comma (,) 

72-73 2 The type of device where 

the error 

occurred (always DA for 
direct access) 

74 1 Comma (,) 

75-82 8 The ddname of the DD 

statement defining the data 
set where the 
error occurred 

83 1 Comma (,) 



Figure 1 1 (Part 2 of 4). Physical Error Message Format 
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Fidd 

Channel 



Message 



Bytes Length Discussion 

84-89 6 The channel command that 

caused the error in the first 
two bytes, followed by "_OP" 

90 1 Comma (,) 

9 1 - 1 05 15 Messages are divided 

according to ECB condition 
codes: 



XMr "INCORR LENGTH" 
"UNIT EXCEPTION" 
"PROGRAM CHECK" 
"PROTECTION CHK" 
"CHAN DATA CHK" 
"CHAN CTRL CHK" 
"INTFCE CTRL CHK" 
"CHAINING CHK" 
"UNIT CHECK" 

If the type of unit check can 
be determined, the 'UNIT CHECK' 
message is replaced by one of 
by one of the following: 

"CMD REJECT" 
"INT REQ" 
"BUS OUT CK" 
"EQP CHECK" 
"DATA CHECK" 
"OVER RUN" 
**T^CKt:ONDCK" 
"SEEK CHECK" 
"COUNT DATA CHK" 
"TRACK OVERRUN" 
"CYLINDER END" 
"NO RECORD FOUND" 
"FILE PROTECT" 
"MISSING A.M." 
"OVERFL INCP" 

X'48' "PURGED REQUEST" 

X'4A' "I/O PREVENTED" 

XMF' "R.HA.RO. error" 



For any other ECB condition code: 

"UNKNOWN COND." 
Figure 1 1 (Part 3 nt 4). Physical Error Message Formal 
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Fidd 



Physical 
Direct Access 
Address 



Access 
Method 



Bytes Length Discusaon 

106 1 Coaima(,) 

107-120 14 BBCCHHR (bin, cylinder, 

head, and record) 

121 1 Comma (,) 

122-127 6 "VSAM" 



Figure 1 1 (Part 4 of 4), Physical Error iVIessage Format 



Return Codes from Macros Used to Share Resources among Data Sets 

VSAM has a set of macros that enables you to share I/O buffers, I/O related 
control blocks, and channel programs among VSAM data sets. 

Return Codes from BLDVRP 

VSAM returns a code in register 15 that indicates whether the BLDVRP request 
was successful: 

Return 

Code Condition 

0(0) VSAM completed the request. 

4(4) The requested data resource pool or index resource pool already exists 
in the address space (LSR) or in the system protect key (GSR). 

8(8) There is not enough virtual storage space to satisfy the request. 
GETMAIN or ES TAE faUed. 

12(C) Buffers cannot be fixed in real storage. PAGEFIX failed. 

16( 10) TYPE = GSR is specified but the program that issued BLDVRP is 
not in supervisor state with protection key 0 to 7. 

20(14) STRNO is less than 1 or greater than 255. 

24(18) BUFFERS is specified incorrectly. A size or number is invalid. 

28(1C) The requested resource pool is invalid. A SHRPOOL value greater 
than 15 was specified. 
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32(20) The resource pool already exists above 16 megabytes and the request 
was for storage below 16 megabytes, or the resource pool already 
exists below 16 megabytes and the request was for storage above 16 
megabytes. 

I 36(24) BLDVRP was issued to build an index resource pool but the required 

I corresponding data resource pool does not exist. 

Return Codes from DLVRP 

VSAM returns a code in register 15 that indicates whether the DLVRP request 
was successful: 

Return 

Godc Condition 

0(0) VSAM completed the request. 

4(4) There is no resource pool to delete. 

8(8) There is not enough virtual storage space to satisfy the request. 
GETMAIN or ESTAE failed. 

12(C) There is at least one open data set using the resource pool. 

16(10) TYPE = GSR is specified, but the program that issued DLVRP is not 
in supervisor state with protection key 0 to 7. 

Return Codes from End-of-VoIume 

End-of-voiumetetumsthe^Uowing codes in register IS: 
Return 

Code Condition 

0(0) Successful. 

4(4) The requested volume could not be mounted. 

8(8) The requested amount of space could not be allocated. 

12(C) I/O operations were in progress when end-of-volume was requested. 

16(10) The catalog could not be updated. 
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Chapter 2. VSAM Macro Formats and Examples 



This chapter contains macro instruction formats and examples. 

The macros that work at assembly time allow you to specify subparametcr values 
as absolute numeric expressions, character strings, codes, and expressions that 
generate valid relocatable A-type address constants. The macros that work at 
execution allow you also to specify these values as: 

• Register notation, where the expression designating a register from 2 through 
12 is enclosed in parentheses; for example, (2) and (REG), where REG is a 
label equated to a number from 2 through 12 

• An expression of the form (S.scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form 

• An expression of the form (♦,scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form, and the 
address specified by scon is indirect— that is, it gives the location of the area 
that contains the value for the subparametcr. 

For most programming applications, you can conveniently use register notation 
or absolute numeric expressions for numbers, character strings for names, and 
register notation or expressions that generate valid A-type address constants for 
addresses. Appraidis C, "Operand Notation" on page 181, ^ves all the ways of 
coding each parameter for the macros that work at execution time. 

You can write a reentrant program only with execution-time macros. 
Appendix B, "List, Execute, and Generate Forms of Macros" on page 171, 
describes alternative ways of coding these macros for reentrant programs. TTiis 
chapter describes the standard form of these macros. 
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ACB 

i ACB Macro (<!!lenerate an Access Method Control Block at Assembly 
I Time) 



The fonnat of the ACB macro is: 



[labeli 


ACB 


lAM-VSAMI 






|,BSTRNO « number] 






IBUFND ^mwiber] 






IBVVNl-' number] 






|,BUFSP = /i«m6e/1 






(,CATALOG = YES|Na| 






|,CRA = SCRA|UCRA| 






IDD^XME^ ddname] 






IjEXLST = address\ 






I,MACRF= (|ADR|I,CNV||,KEYI 






|,CFX|NFX| 






|,DI)N|DSN| 






|,DFR|NI>n 






|,DIR||,SE2II,SKP| 






MCIjNCII 






|,IN1I,GUTI 






l,NiS)SISl 






|,NRM|AIX| 






|,NRS|RST| 






|,NSR|LSRiGSRi 






|,NIJB|L'BFI)| 






|,MAREA = aic/rejj| 






\^\V.¥N^ number\ 






I,PASS\VD»ae/</rej4 






|,R.MODE3l = f ALLIBUFFICBINONE)! 






|,SHRPOOL= {^number}\ 






I,SrRNO = /i«/nM 



I Note: The RMODE3i parameter replaces the AMODE31 subparameter shown 

i in previous releases. 

Values for ACB macro subparamcters can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-typc address constants. 

label 

is 1 to 8 characters that provide a symbolic address for the access method 
control block that is assembled and also, if you omit the DDNAME 
parameter, serves as the ddname. 

AM = VSAM 

specifies that the access method using this control block is VSAM. 

BSTRNO- number 

specifies the number of strings initially allocated for access to the base 
cluster of a path. The default is STRNO. BSTRNO is ignored if the 
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object being opened is not a path. If the number specified for BSTRNO is 
insufficient, VSAM will dynamically extend the number of strings as needed 
for the access to the base cluster. BSTRNO can influence performance. 
The VSAM control blocks for the set of strings specified by BSTRNO are 
allocated on contiguous virtual storage, whereas this is hot guaranteed for 
the strings allocated by dynamic extension. 

BVVSD'' number 

specifics the number of I/O buffers VSAM is to use for transmitting data 
between virtual and auxiliary storage. A buffer is the size of a control 
interval in the data component. The minimum number you may specify is 
1 plus the number specified for S TRNO (if you omit STRNO, BUI'ND 
must be at least 2, t»ecause the default for STRNO is 1). The number can 
be supplied by way of the JCL DD AMP parameter as well as by way of 
the macro. The default is the minimum number required. Note, however, 
that minimum buffer specification does not provide optimum sequential 
processing performance. Generally, the more data buffers specified, the 
better the performance. Note also that additional data buffers will benefit 
direct inserts or updates during control area splits and will benefit spanned 
record accessing. For more information, see "Optimizing Performance" in 
VSAM Adminbtration Guide. 

BVFSl-^ number 

specifies the number of I/O buffers VSAM is to use for transmitting the 
contents of index entries between virtual and auxiliary storage for keyed 
access. A buffer is the size of a control interval in the index. The 
minimum number is the number specified for STRNO (if you omit 
STRNO, BUFNI must be at least 1, because the default for STRNO is 1). 
You can supply the number by way of the JCL DD AMP parameter as 
well as by way of the macro. The defauh is the minimum number 
required. 

Additional index buffers will improve performance by providing for the 
residency of some or all of the high-level index, thercl>y iriimimzing the 
number of high-level index records to be retrieved from DASD for 
key-direct processing. For more information, see "Optimizing 
Performance" in VSAM Administration Guide. 

BVrSP'' number 

specifies the maximum number of bytes of virtual storage to be used for the 
data and index I/O buflcrs. VSAM gets the storage in your program's 
address space. If you specify less than the amount of space that Was 
specified in the BUFFI2RS PACE parameter of the DEITNB command 
when the data set was defmed, VSAM overrides your BUFSP specification 
upward to the value specified in BUFFERSPACE. (BUFFERSPACE, by 
definition, is the least amount of virtual storage that will ever be provided 
for I/O buffers.) You can supply BUFSP by way of the JCL DD AMP 
parameter as well as by way of the macro. If you don't specify BUFSP in 
either place, the amotmt of storage used for bufifer allocation is the largest 
of: 

• The amount specified in the catalog (BUFFERSPACE), 

• The amount determined from BUFND and BUFNI, or 
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• The minimum storage required to process the data set with its specified 
processing options 

If BUFSP is specified and the amount b smaller than the minimum 
amount of storage required to process the data set, VSAM cannot open the 
data set. 

A valid BUFSP amount takes precedence over the amount called for by 
BUFND and BUFNI. If the BUFSP amount is greater than the amount 
called for by BUFND and BUFNI, the extra space is allocated as ^Uows: 

• When MACRF indicates direct access only, additional index buffers are 
allocated. 

• When MACRF indicates sequential access, one additional index buffer 
and as many data buffers as possible are allocated. 

If the BUFSP amount is less than the amount called for by BUFND and 
BUFNI, the number of data and index buffers is decreased as follows: 

• When MACRF indicates direct access only, the number of data buffers 
is decreased to not fewer than the minimum number. Then, if required, 
the number of index buffers is decreased until the amount called for by 
BUFND and BUFNI complies with the BUFSP amount. 

• When MACRF indicates sequential access, the number of index buffers 
is decreased to not fewer than 1 more than the minimum number. 
TTien, if required, the number of data buffers is decreased to not fewer 
than the minimum number. If still required, 1 more is subtracted from 
the number of index buffers. 

• Neither the number of data buffers nor the number of index buffers is 
decreased to fewer than the minimum number. 

If the index doesn't exist or isn't being opened, only BUFND, and not 
BUFNI, enters into these calculations. The bufferspace must not exceed 
16776704. 

CATALOG = YES|NO 

specifies whether a catalog is being opened as a catalog (YES) or as a data 
set (NO). When NO is coded (or taken as the default), you can process the 
catalog with request macros (GET, PUT, etc). Your program must be 
APF-authorized to process a catalog as a data set. To open a password 
protected catalog for processing with VSAM macros, you must supply its 
master password. When CATALOG - YES is coded, the catalog must be 
processed with an SVC designed for that purpose. (Access method services, 
for example, processes catalogs with SVC 26.) The request macros are 
invalid for processing a catalog "as a catalog." VSAM users should alter the 
contents of a catalog only by access method services commands. 

CRA>SCRA|UCRA 

specifies that a catalog recovery area is to be opened and that the control 
blocks are to be built in either system storage (SCRA) or user storage 
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(UCRA). If you specify SCRA and issue record management requests, you 
must operate in key 0. If you specify UCRA, you must be authorized by 
the system and you must supply the master password of the master catalog. 

DDNAME'^ ddname 

is 1 to 8 characters that identify the data set that you want to process by 
specifying the JCL DD statement for the data set. You may omit 
DDNAME and provide it by way of the label or by way of the MODCB 
macro before opening the data set. MODCB is described later in this 
chapter. 

EXLST^ address 

specifies the address of a list of addresses of exit routines that you are 
providing. The list is established by the EXLST or GENCB macro. If you 
use the EXLST macro, you can specify its label here as the address of the 
exit list. If you use GENCB, you can specify the address returned by 
GENCB in register 1 or the label of an area you supplied to GENCB for 
the exit list. Omitting this parameter indicates that you have no exit 
routines. Exit routines are described in "User- Written Exit Routines" in 
Data Facility Product: Customization. 

MACRF = nADRII.CNVIi. KEYI 
l.CFXI NFXl 
I. DDN IDSNI 
|,DFR|NDF| 
f.DlRif.SEOH.SKPl 
MCIINCII 
l,INj|,OUTI 
LMSISISj 
1. NRM IAIXI 
1.NRSIRSTI 
LNSRILSRIGSRI 
iNUBlUBFj) 

specifies the kind(s) of processing you will do with the data set. The 
subparameters must be meaningful for the data set. For example, if you 
specify keyed access for an entry-sequenced data set, you cannot open the 
data set. You must specify all the types of access you're going to use, 
whether you use them concurrently or by switching from one to the other. 
Figure 12 on page 3S ^ves the subparameters; each group of 
subparameters has a default value (indicated by underlining). You may 
specify subparameters in any order. You may specify both ADR and KEY 
to process a key-sequenced data set. You may specify both DIR and SEQ; 
with keyed access, you may specify SKP as well. If you specify OUT and 
want merely to retrieve some records as well as update, delete, or insert 
others, you need not also specify IN. 

I Note: The RM0DE31 parameter rephces the AMODE31 subparameter 

i shown in previous releases. 
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option Meaning 

AOR Addressed access to a key-scquenced or an cntry-sequenced data 

set; RBAs arc used as search ai^uments and sequential access b by 
entry sequence. 

CNV Access is to the entire contents of a control interval rather than to 

an individual data record. If the data set is password protected, 
you must supply the address of the control or higher-level 
password in the ACB PASSWD parameter. 

KEY Keyed access to a kcy-sequenced or relative record data set; keys 

or relative record numbers are used as search arguments and 
sequential access is by key or relative record number. 

CFX Control blocks and I/O buffers are to be fixed in real storage; 

MACRF = ICI must also be specified. 

NF7C Control blocks and I/O buffers are fixed in real storage only 

during I/O operations. 

DDN Subtask shared control block connection is based on common 

ddnamcs. 

DSN Subtask shared control block connection is based on common 

datar set names. 

DFR With shared resources, writes for direct PUT requests are deferred 

until the WRTBFR macro is issued or until VSAM needs a buffer 
to satisfy a GET request; deferring writes saves I/O requests in 
cases where subsequent requests can be satisfied by the data 
already in the buffer pool. 

NDF Writes are not to be deferred for direct PUTs. 

DIR Direct access to a key-sequenccd, entry-sequenced, or a relative 

record data set. 

SEC Sequential access to a key-scquenced, entiy-sequcnced, or a 

relative record data set. 

SKP Skip-sequential access to a key-sequenced or a relative record data 

set; used only with keyed access in a forward direction. 

ICI Processing is limited to improved control interval processing; 

access is faster because fewer processor instructions are executed. 

NCI Processing other than improved control interval processing. 

IN Retrieval of records of a key-sequenccd, entry-sequenced, or a 

relative record data set; (not allowed for an empty data set). If the 
data set is password protected, you must supply the address of the 
read or hi^er-level password in the ACB PASSWD parameter. 

Figure 12 (Part I of 2). MACRF Options 
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Option Meaning 

OUT Storage of new records in a key-sequcnced, entry-sequenced, or 
relative record data set (not allowed with addressed access to a 
key-sequenccd data set); update of records in a kcy-scquenced, 
entry-sequenced, or relative record data set; deletion of records from a 
key-sequcnced data set or relative record data set. 

If the data set is password protected, you must supply the address of 
the update or hi^er-Ievcl password in the ACB PASSWD parameter. 

NIS Normal insert strategy. 

SIS Sequential insert strategy (split control intervals and control areas at 
the insert point rather than at the midpoint when doing direct PU'I s); 
although positioning is lost and writes arc done after each direct PUT 
request, SIS allows more efiicient space usage when direct inserts are 
clustered around certain keys. 

NRM The object to be processed is the one named in the specified ddname. 

AIX 'llie object to be processed is the alternate index of the path specified 
by ddname, rather than the base cluster via the alternate index. 

NRS Data set is not reusable. 

RST Data set is reusable (high-used RBA is reset to 0 during OPEN). If 
the data set is password protected, you must supply the address of the 
update or higher-level password in the ACB PASSWORD parameter. 

NSR Nonshared resources. 

LSR Local shared resources. Each address space may have up to 16 index 
resource pools and 16 data resource pools independent of other 
address spaces. Unless you are using the default, SIIRPOOL = 0, you 
must specify the SlIRPDOlv parameter to indicate which resource 
pool you are using. Specifying LSR will cause a data set to use the 
local resource pool built by the BLDVRP macro. If an index 
resource pool exists at the time an OPEN macro is issued, the index 
for a key-scquenced data set will be coimectcd to the index resource 
pool. 

GSR Global shared resources; all address spaces may have local and global 
resources pools, where tasks in an address space with a local resource 
pool may use either the local resource pool or the global resource 
pool. 

NUB Management of I/O buffers is left up to-^VSAM. 

UBF Management of I/O buffers is left up to the user; the work area 

specified by the RPL (or GENCB) AREA parameter is, in effect, the 
I/O buffer— VSAM transmits the contents of a control interval directly 
between the work area and direct access storage; valid when 
OPTCD=MVE and MACRF=CNV are specified; when ICI is 
specified, UBF is assumed. 

Figure 12 (Part 2 of 2). MACRF Options 
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MAREA'^ address 

specifies the address of an optional OPEN/CLOSE or TYPE = T option 
(CLOSE macro) messa^ area. See "OPEN/CLOSE Message Area for 
Multiple Reason or Warning Messages" on page 7 for more information. 

MLEN = number 

specifies the length of an optional OPEN/CLOSE or TYPE = T option 
(CLOSE macro) message area. Default = 0; maximum = 32K. See 
"OPEN/CLOSE Message Area for Multiple Reason or Warning Messages" 
on page 7 for more information. 

PASSWD^ address 

specifics the address of a field that contains the highest-level password 
required for the typc(s) of access indicated by the MACRF parameter The 
first byte of the field pointed to contains the length (in binary) of the 
password (maximum of 8 bytes). Zero indicates that no password is 
supplied. If the data set is password protected and you don't supply a 
required password in the access method control block, VSAM will give the 
console operator the opportunity to supply it when you open the data set. 

RMODE31 = rALLIBUFFICBI NONEI 

specifics where VSAM OPEN is to obtain virtual storage (above or below 
16 megabytes) for control blocks and I/O buffers. 

The values specified by the RMODE31 parameter only have an effect on 
VSAM at the setting just before an OPEN is issued. At all other times, 
changing these values has no eifect on the residency of the control blocks 
and I/O buffers. 

ALL 

both VSAM control blocks and I/O buffers are to be obtained above 
16 megabytes. 

BUFF 

only VSAM I/O buffers are to be obtained above 16 megabytes. 

CB 

only VSAM control blocks are to be obtained above 16 megabytes. 
NONE 

both I/O buffers and VSAM control blocks arc to be built below 16 
megabytes. This is the default. 

Note: In previous releases, the MACRF subparameter AMODE31 
specified that I/O buffers were to be obt£uncd above 16 megabytes and that 
the caller was running in 31-bit addressing mode. The RMODE31 
parameter replaces the AM0DE31 subparameter and the two are mutually 
exclusive. If both the AM0DE31 subparameter and the RMODE31 
parameter are specified within the same program, AMODE31 is ignored. 

SHRPOOL'' {number\0} 

identifies which LSR pool is to be connected to the ACB. This parameter 
is valid only when MACRF = LSR is also specified. The identification 
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number of the shared pool must be a number from 0 to 15. The default is 
0. 

SJKNO" number 

specifies the number of requests requiring concurrent data set positioning 
VSAM is to be prepared to handle. The default is 1. A request is defined 
by a given request parameter list or chain of request parameter Usts. See 
**RPL Macro (Generate a Request Parameter List at Assembly Time)" on 
page 126 and "GENCB Macro (Generate a Request Parameter List at 
Execution Time)" on page 80 for information on request parameter lists. 
When records are loaded into an empty data set, the STRNO value in the 
access method control block must be 1. 

VSAM dynamically extends the number of strings as they are needed by 
concurrent requests for this ACB. This automatic extension can influence 
performance. The VSAM control blocks for the set of strings specified by 
STRNO are allocated on contiguous virtual storage, but this is not 
I guaranteed for the strings allocated by dynamic extension. Dynamic string 

I addition caimot be done when using the following options: 

• Load mode 

• ICI 

• LSR or GSR 

I For STRNO, you should specify the total number of request parameter 

lists or chains of request parameter lists that you are using to dcfme 
requests. (VSAM needs to remember only one position for a chain of 
request parameter lists.) However, each position beyond the minimum 
number that VSAM needs to be able to remember requires additional 
virtual storage space for: 

• A minimum of one data I/O buffer and, for keyed access, one index 
I/O bu£&r (the jizc of an J/O buffer is the control interval si^e of a data 
set) 

• Internal control blocks and other areas 



Chapter 2. VSAM Macro Formats and Examples 4 1 



ACB 



Example 1: ACB Macro 



In this example, the ACB macro is used to identify a data set to be opened and 
to specify the types of processing to be perfonned. The access method control 
block generated by this example is built when the program is assembled. 

BLOCK ACB AM~VSAM,BUFNI>»4, BLOCK gives symbolic 
BUFNI~3, address of the access 

BUFSP=19456, method control blbck. 

DDNAME=DATASETS, 
EXLST=EXITS, 

MACRF=(KEY, DIR. SEQ, OUT) , 

PASSVD»FIELD» 

STRN0=2 

FIELD DC FL1*6',C'CHAN6£' The update password: 

CHANGE has 6 characters. 

The ACB macro's parameters arc: 

• BUFND specifies four I/O buffers for data; BUFNI specifies three I/O 
buffers for index entries; ^d BUFSP specifics 19456 bytes of buffer space, 
enough space to accommodate control intervals of data that arc 4096 bytes 
and control intervals of index entries that arc 1024 bytes. 

• DDNAME ^€ifie& that this access method con^oi block i& a^ociated with 
a DD statement named DATASETS. 

• EXLST specifies that the exit list associated with this access method control 
block is named EXITS. 

• MACRF specifies keyed-direct and keyed-sequential processing for both 
msertion and update. 

• PASSWD specifies the location, FIELD, of the password provided. FIELD 
contains the length of the password as well as the password itself. 

• STRNO specifies that two requests will require concurrent positioning. 
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Example 2: ACB Macro 

In this example, the ACB macro is used to identify a data set to be opened and 
to specify the types of processing to be performed. An LSR pool is connected to 
the data set. The access method control block generated by this example is built 
when the program is assembled. The caller requests that the VSAM control 
blocks and I/O buffers be obtained above 16 megabytes if possible. 

BL0CK2 ACB AM=VSAM, 

DDNAME=DATASETS, 
EXLST=EXITS, 
MACRF=(KEY,DIR, 
LSR,SEQ,OUT), 
PASSWD=FIELD, 
RHODES 1=ALL, 
SHRP00L=1 

FIELD DC FLl * 6 ' , C ' CHANGE * The update password : 

CHANGE has 6 characters. 

The ACB macro's parameters are: 

• DDNAME specifics that this access method control block is associated with 
a DD statement named DATASETS. 

• EXLST specifies that the exit list associated with this access method control 
block is named EXITS. 

• MACRF specifies keyed-direct and keyed-sequential processing for both 
insertion and update. LSR indicates that the Ii>R pool created by BLDVRP 
is to be connected to the data set. 

• PASSWD specifies the location, FIELD, of the password provided. FIELD 
contains the l(»igth of the password as well as the password itself. 

• RMODE31 = ALL specifies that you want both VSAM control blocks and 
I/O buffers to reside above 16 megabytes. 

• SHRPOOL specifies that the LSR pool with the identification number of 1 is 
to be used. However, if an index resource pool exists at the time the OPEN 
macro is issued, the index for the key-sequenced data set will be connected to 
the index resource pool. 



BL0CK2 gives symbolic 
address of the access 
method control block. 
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ACQRANGE Macro (Stage Data) 

The fotxnat of the ACQRANGE macro is: 



[labeli ACQRANGE RPL' address 



RPL" address 

specifies the address of the RPL that identifies your open data set and your 
argument range. RPL parameters that have meaning for ACQRANGE are 
as follows: 



ACB^ ad{iress 

identifies your VSAM data set. 



ARG » address 

identifies your starting and ending arguments. Address points to a 
parameter list, aligned on a fuUword boundary as follows: 



KEY-SEQUENCED DATA SET 

Offset Length Contents 

0 4 Feedback area: Address 

of an ECB WAIT list 

4 K Starting full argument 

(K - key length) 

4+K K (K = key length) 



ENTRY-SEQUENCED DATA SET OR RELATIVE RECORD 
DATA SET 

Offset Length Contents 

0 4 Feedback area: Address 

of an ECB WAIT list 

4 4 Starting RBA/RRN 

8 4 Ending RBA/RRN 

The maximum number of argument pairs you may specify is one. 

OPTCD = ({ADR|KEY} 
,{ASY|SYN) 
,(KEQ|KGE} 
,FKS) 

ADR is valid for an entry-sequenced data set, error for key-sequenced 
data set or relative record data set. 
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KEY is valid for key-sequenced data set and relative record data set, 
error for cntiy-sequenced data set. 

If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of event 
control blocks (ECB) (in standard WAIT list format) which you may 
use in place of the RPLECB field. 

GEN is not supported; if specified, it wiU g^ve an error indication. 

All other OPTCD subparameters are not applicable, and, if specified, 
are ignored with no error indication. 

Because your request may result in the sta^g of numerous cylinders, a single 
ECB is not sufficient for an asynchronous ACQRANGE request. Tlie RPLECB 
field is inoperative for the ACQRANGE interface. Upon return from an 
asynchronous ACQRANGE, the feedback area of the ACQRANGE parameter 
contains the address of a standard ECB WAIT list. You must then use this list 
in conjunction with either the WAIT macro or the EVENTS macro of MVS. 
An asynchronous request must conclude with cither CHECK, ENDREQ, or 
CLOSE, llie parameter list carmot be reused until the CHECK, ENDREQ, or 
CLOSE is completed. 

At the conclusion of this macro, the RPL is disconnected. Any positioning in 
effect prior to execution of ACQRANGE will be lost. You may have to 
reposition. Chained RPLs are not supported by this macro. 
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BLDVRP Macro (Build VSAM Resource Pool) 



The fonnat of the BLDVRP macro is: 



BLDVRP 


BUFFERS = (siz€{number)tSize(nu/nber)i...) 




(,FIX = {BFR|IOB|(BFRJOB)}| 




(,KEVLEN = /e/i^r/i| 




I.RMODE31 - f ALLIBUFFICBINONE}! 




[,SHRPOOL= {0|/?MwMI 




I,MODE={24|3T}| 




,STRSO^ number 




|,TVFE=fLSR|,DATA|INDEX| | GSR}| 



Note: The RMODE31 parameter replaces the LOC= BELOW|ANY parameter 
shown in previous releases. 

The BLDVRP macro has a standard form and list and execute forms. The 
standard form builds a parameter list and passes control to VSAM to build the 
resource pool. The list and execute forms are described in Appendix B, "List, 
Execute, and Generate Forms of Macros" on page 171. 

BUFFERS = {size{number)ySize{numb€r)f..,) 

specifics the size and number of buffers in each buffer pool in the resource 
pool. The number of buffer pools in the resource pool is implied by the 
number of size(number) pairs you specify. 

VVhcn you process a key-scqucnced data set, the index component, as well 
as the data component, shares the buffers of a buffer pool. When you use 
an alternate index to process a base cluster, the components of the alternate 
index and the base cluster share buffers. The components of alternate 
indexes in an upgrade set share buffers. Buffers of the appropriate size and 
number must be provided for all these components. Each component uses 
the buffer pool with buffers either the required size or larger. 

size 

is 512, 1024, 2048, 4096, and then in increments of 4096 to a 
maximum of 32K bytes. 

number 

is at least 3. 

Size times number must be less than 16 megabytes. 

FIX= {BFR|IOBi(B(ll,IOB)} 

specifies that I/O buffers (BFR), or I/O-rclatcd control blocks (lOB), or 
both, are to be fixed in real storage. With GSR, 10 B includes channel 
programs. If the program that issues BLDVRP with FIX specified is not 
authorized to fix areas in real storage, FIX is ignored. A program is 
authorized if it is in supervisor state with protection key 0 to 7, or has been 
link-edited with authorization (the authorized program facility is described 
in Supervisor Services and Macro Instructions), 
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Note: If FIX is specified, DLVRP must be issued by the same task that 
issues BLDVRP. 

KEYLEN = /e/2g/A 

specifies the maximum key length of the data sets that are to share the 
resource pool. The default is 255. The keys whose lengths must be 
provided for are the prime key of each key-sequenccd data set and the 
alternate key of each alternate index that is used for processing or is being 
upgraded. If none of the data sets is keyed, specify 0. 

RMODE3I - fALLIBUFFICBI NONE) 

specifies the storage residence location of the buffers and I/O related control 
blocks of the LSR pool identified with the SIIRPOOL keyword. 

The RMODE31 parameter tells the VSAM OPEN routines where to 
obtain storage for the I/O related control blocks and I/O buffers. 
Therefore, the only time the values specified by the RMODE31 parameter 
have any effect on VSAM is on the setting just before an OPEN is issued. 
At other times, changing these values has no effect on the residency of the 
I/O related rontrol blocks and I/O buffers. 

Note: The RMODE31 parameter is valid only when TYPE = LSR is 
specified. 

ALL 

both I/O buffers and the VSAM I/O related control blocks associated 
with the pool arc to reside above 16 megabytes. 

BUFF 

specifies that only I/O buffers arc to rcsidc above 16 megabytes. 

CB 

<Kny the VSAM I/O related (xnttrol blocks mssoeiated "with the pool 
^1, arc to reside above 16 megabytes. 

NONE 

both I/O buffers and the VSAM I/O related control blocks associated 
with the pool are to reside below 16 megabytes. This is the defauh. 

Note: In previous releases, the LOC = (BELOW|ANY) parameter was 
used to specify that buffers in the pool be created above 16 megabytes. The 
RM0DE31 parameter replaces the LOC parameter and the two parameters 
are mutually exclusive. If both are specified on the BLDVRP macro, the 
LOC parameter is ignored. 

SHRPOOL « {W^number) 

specifics the identification number of a shared resource pool. Valid only 
when TYPE = LSR is also specified or defaulted. This parameter also 
requires that the RMODE31 parameter be specified. 

0 

specifies the shared pool with the ID of 0. It is the default LSR pool. 
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number 

specifies the shared pool with the ID of number ^Yiqk number can be 
0 to 15. The LSR control block and buffer pool residence is 
determined by the RMODE3I = keyword. 

MODE -{24(31} 

specifies the format of the BLDVRP parameter list that is to be generated. 
24 

specifies that a standard form (24-bit) parameter list address be 
generated. This is the default. 

31 

specifies that a long form (31 -bit) parameter list address be generated, 
lliis value must be coded if the parameter list resides above 16 
megabytes. 

STRSO^ number 

specifies the total number of placeholders required for all the data sets that 
are to share the resource pool. 1 is minimum; 255 is maximum. 

The number should equal the potential number of requests that may be 
issued concurrently for all the data seXs that wilt share the i^ourcc pool If a 
request fails because the number of placeholders is insufficient (you receive a 
reason code of 64 (X'40') in the RPL feedback area), you may retry the 
request; it will be assigned a placeholder if one has been released. See 
Figure 8 on page 17 for a complete description of reason code 64 (X'40'). 

TYPE= f LSRLDATA IIXDEXI | GSR) 

specifies whether a local (LSR) or a global (GSR) resource pool is to be 
built. 

LSR 

specifies that the caller requests a local shared resource pool. A 
maximum of 16 data and 16 index resource pools can be built in one 
address space. Each resource pool must be built individually. 

DATA 

specifies that the caller wants to build a data resource pool. This 
option requires that LSR be specified. This resource pool must exist 
before an index pool with the same shared pool ID can be built. 

INDEX 

specifies that the caller wants to build an index resource pool. This 
option requires that LSR be specified or defaulted. INDEX must be 
specified in order to create a separate index resource pool. If it is not 
specified, both data and index components will use the data pools. A 
data pool must already exist before an index pool with the same 
shared pool ID can be built. 

GSR 

specifies that the caller requests a global shared resource pool. 
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Only one BLDVRP TYPE = GSR may be issued for the system for each of 
the protection keys 0 through 7. The program that issues BLDVRP 
TYPE GSR must be in supervisor state with protection key 0 to 7. 

Example 1. Obtaining an LSR Pool above 16 Megabytes 

This example shows how both a local shared resource pool and a BLDVRP 
parameter list residing above 16 megabytes arc obtained. 

POOLl BLDVRP BUFFERS=( 1024(5)), 
STRN0=4, 
TYPE=LSR, 
M0DE=31, 
RM0DE31=ALL 

The BLDVRP parameters axe: 

• BUFFERS specifies that there is one buffer pool in the resource pool. This 
buffer pool contains 5 buffers, and each of these buffers is 1024 bytes. 

• STRNO specifics that 4 placeholders arc required for the data sets to share 
the resource pool. 

• TYPE specifics that a local resource pool is to be built. 

• MODE specifies that a parameter list is to be generated that may reside 
above or below 16 megabytes. The value of 31 must be coded if the 
parameter list resides above 16 megabytes. 

• RMODE31 specifies the location in storage for the I/O buffers and I/O 
related control blocks of the LSR pool. 

To connect the LSR pool to the data set, you must code the LSR and 
S1IRPOOL parameters on the ACB. See "ACB Macro (Generate an Access 
Method Control Blot': at Assembly Time)" on page 34. 
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I Example 2. Request for Separate Data and Index Resource Pools 



This example shows how the two separate data and index resource pools with an 
identification equal to 3 are created. 



POOLl BLDVRP 



•fe 

P00L2 



LTR 
BNZ 



BLDVRP 



BUFFERS=( 2048(4)), 

TYPE=(LSR,DATA), 

SHRP0OL=3, 

STRN0=2, 

RM0DE31=ALL 

R15,R15 
ERROR 



BUFFERS=( 1024(5)), 
TYPE=(LSR, INDEX), 
SHRP00L=3, 
STRN0=2, 
RM0DE31=ALL 



Check return code. 
Do not build index if 
error. 



Note: POOLl must be created first because the data pool must exist before the 
index pool with the some shared pool ID can be built. Also, only one data and 
one index pool can be built for a shared pool ID. 



50 MVS/XA VSAM Administration: Macro Instruction Reference 



CHECK Macro (Wait for Completion of Request) 



CHECK 



The format of the CHECK macro is: 



\Iabei\ 



CHECK 



RPL^ address 



where: 



label 



is 1 to 8 characters that provide a symbolic address for the CHECK macro. 
RPL'= address 

specifics the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
gpnerates a valid relocatable A-type address constant. 



Example 1: Check Return Codes after an Asynchronous Request 



In this example, return codes arc checked after an asynchronous request, llie 
CHECK macro is used to cause an exit to be taken if there is a lo^pcal or 
physical error or if the end of the data set is reached. 

REQPARMS RPL OPTCD=ASY 



GET RPIr=REQPARMS 



LTR 



6NZ 



15,15 



REJECTED 



CHECK RPL=REQPARMS 



LTR 15,15 
BNZ FAILURE 



Was the request completed 
successfully? 

Zero indicates the request was 
accepted. If it was not 
accepted, register 15 contains 

REQPARMS is active for 
another request. Continue to 
work on something that is not 
dependent on the request. 

CHECK would cause one of the 
three exits to be taken if 
there was a logical or physical 
error or if the end of the 
data set was reached and an 
active exit list exists. 

Test return indication is 
register 15. 

Zero indicates the request 
completed successfully. If 
it failed, register 15 
contains 8 or 12: there was 
a logical or a physical 
error. 



REJECTED ... 
FAILURE . . . 
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Unless you provide exit routines that terminate processing, always test rc^stcr IS 
after the CHECK. If a routine returns to VSAM, re^ster 15 is reset and control 
is passed back to your program immediately after the CHECK. An error analysis 
routine normally issues SHOWCB or TESTCB to examine the feedback field in 
the request parameter list, so that, when your processing program gets control 
back, it doesn't have to analyze the errors-^but it may' alter its processing if there 
was an error. If you don't provide an error analysis routine, your program can 
issue SIIOVVCB or TESTCB to analyze an error when it gets control back 
following the CHECK. 



Example 2: Check Return Codes after a Synchronous Request 



With synchronous processing, you should test register 15 after the request 
because the request may not have been accepted (re^ster 15 contains 4) or 
because an error might have occurred (8 or 12): 

GET RPL=REQPARMS 

LTR 15,15 Was the request completed 

successfully? 

BNZ REJFAIL If branch is not taken, was 

the request accepted and 
completed succes fully? 

REJFAIL . . . 



Example 3: Overlap Processing 



In this example, the CHECK macro is used to wait for completion of a request 
before continuing to other processing. Access is asynchronous. 



BLOCK 
LIST 



ACS 
RPL 



ACB-BLOCK, Asynchronous access. 

AREA=WORK, 

AREALEN=50, 

OPTCD=ASy 



LOOP GET RPL=LIST 
LTR 15,15 
BNZ NOTACCEP 

Do other processing. 

CHECK RPL=LIST 

LTR 15,15 
BNZ ERROR 
Process the record. 

B LOOP 



Suspends your processing to wait 
for completion of GET if 
necessary and to cause VSAM to 
indicate return codes. 
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NOTACCEP ... 
ERROR 



Request wds not accepted. 
Request failed. 



WORK 



DS 



CL50 



Work area. 



After issuing the request, make sure that VSAM accepted it before you go on to 
other processing. When you have done as much other processing as you can, 
issue the CHECK macro. VSAM will not give you back control until the 
request is complete. If you don't want to issue CHECK until you know the 
request is complete, use the ECB parameter of the RPL macro or the 
10 = COMPLETE parameter of the TESTCB macro. After you issue the 
CHECK, VSAM immediately returns a code and takes an ent, if necessary. See 
"RPL Macro (Generate a Request Parameter List at Assembly Time)" on 
page 126 and "GENCB Macro (Generate a Request Parameter List at Execution 
Time)" on page 80 for information on the ECB parameter. 



Example 4: Suspend a Request for Many Records 



In this example, a CHECK macro is issued for the fu"st request parameter list in a 
chain of parameter lists. If an error occurred for one of the request parameter 
lists in the chain and you have supplied error analysis routines, VSAM takes a 
LERAD or SYNAD exit before it returns control to your program after the 
CHECK. 



FIRST RPL 



SECOND RPL 



THIRD RPL 



ACB=BLOCK, 

AREA=AREA1, 

AREALEN=50, 

NXTRPL=SECOND, 

OPTCD=ASY 

ACB=BLOCK, 

AREA=AREA2, 

AREALEN=50, 

NXTRPL=THIRD^ 

OPTCD=ASY 

ACB^'BLOCK, 
AREA=AR£A3, 
AREALEN=50, 
OPTCD=ASY 



Last list does not indicate 
a next list. 



LOOP 



GET 
LTR 
BNZ 



RPL=FIRST 

15,15 

NOTACCEP 



Do other processing. 

CHECK RPL=FIRST 
LTR 15,15 
BNZ ERROR 



Request gives the address of 
the first request parameter 
list. 
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CHECK 



Process the three records retrieved by the GET. 



B 



LOOP 



NOTACCEP ... 



Request wasn't accepted. 



ERROR 



Display the feedback field 
(FIELDS=FDBK) of each request 
parameter list to find 
out which one had an error. 



AREAl 



DS 



CL50 



A single GET request causes VSAM 
to put a record in each of AREAl, 
AREAl, and AREAS. 



AREA2 DS CL50 
AREA3 DS CL50 

After the CHECK, register 15 is set to indicate the status of the request. A code 
of 0 indicates that no error was associated with any of the request parameter lists. 
Any other code indicates that an error occurred for one of the request parameter 
lists. You should issue a SIIOVVCB macro for each request parameter list in the 
chain to find out which one had an error. VSAM doesn't process any of the 
request parameter lists beyond the one with an error. 
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CLOSE Macro (Disconnect Program and Data) 



CLOSE 



The format of the CLOSE macro is: 



{label\ 


CLOSE 


(address[,(options)\,...) 






|,MODE«{24|3I]| 






|,TYPE-T| 



where: 



label 

is 1 to 8 characters that provide a symbolic address for the CLOSE macro. 
address 

specifics the address of the access method control block or DCB for each 
data set to be closed. You may specify the address in register notation 
(using a register from 2 through 12— in parentheses) or specify it with an 
expression that generates a valid relocatable A-type address constant. If 
you specify only one address with a register, you must enclose the 
expression identifying the rctpstcr in two sets of parentheses: for example, 
CLOSE ((2)). 

options 

are options parameters for use only in closing non-VSAM data sets. If any 
options arc spcdficd with the address of an access method control block, 
VSAM ignores them. 

Note: Because the CLOSE parameters arc positional, include a comma for 
options (even if you don't specify options) before a subsequent parameter. 

MODE={24|3l) 

specifics the format of the CLOSE parameter list that is to be built. 

24 

specifies that a standard form (24-bit) parameter list address be built. 
This parameter list must reside below 16 megabytes and contain the 
address of ACBs residing below 16 megabytes. ITic caller, however, 
may be above 16 megabytes. This is the default parameter list 
format. 

31 

specifies that a long form (31 -bit) parameter list address be built. 
This list can reside above or below 16 mcgab>tes. This value must be 
coded if the parameter list resides above 16 megabytes or contains the 
address of an VSAM/VTAM ACB residing above 16 megabytes. 

TYPE»T 

specifics that VSAM is to complete outstanding I/O operations and update 
the catalog, but not disconnect the program from the data. 

You can issue a temporary CLOSE macro to cause VSAM to complete 
outstanding I/O operations, put back into the catalog the updated 
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CLOSE 



information that was brought into virtual storage when the data set was 
opened, and write records in the SMF data set if you are using SMF. A 
temporary CLOSE doesn't discoimect the program from the data set, so 
your program can continue to process the data set without issuing an 
OPEN macro again. 

You must close and reopen a newly created VSAM data set before you can 
issue noncreate requests. A temporary close is not adequate for this 
purpose. 

Note: If you are sharing subtasks or if you have issued an asynchronous request 
for access to a data set, you must issue a CHECK or an ENDREQ on all RPLs 
before you issue a CLOSE or CLOSE TYPE = T; otherwise, concurrent data set 
I/O activity will cause unpredictable results during a close. 



Example: CLOSE Macro 



This example shows how to close an ACB with a parameter list that may reside 
above 16 megabytes. 



BLOCKl 



ACB 



,RM0DE31=ALL 



VSAM control blocks 

and 1/0 buffers laay 
be above 16 megabytes 



OPEN 



CLOSE 



BLOCKl, 
M0DE=31 



BLOCKl, 

M0DE=31, 

TYPE=^ 



OPEN/CLOSE parameter 
list may reside above 
16 megabytes 



llie CLOSE parameters are: 



• MODE = 31 is required if the OPEN/CLOSE parameter list resides above 16 
megabytes or if the ACB resides above 16 megabytes. 

• TYPE indicates a temporary CLOSE. This causes VSAM to complete 
outstanding I/O operations, put back into the catalog the updated 
information that was brought into virtual storage when the data set was 
opened, and write records in the SMF data set if you arc using SMF. 
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CNVTAD 

CNVTAD Macro (Convert Address) 

The format of the CNVTAD macro is: 



\label\ 



CNVTAD 



RPL'^ address 



RPL'^ address 

specifics the address of the request parameter list (RPL). The RPL 
identifies your opened VSAM data set and your arguments. The following 
RPL parameters and subparameters have meaning for the CNVl'AD 
macro: 

ACB = address 

identifies your VSAM data set. 

ARG address 

identifies your arguments, llie address points to a parameter list, 
aligned on a fullword boundary as follows: 

Kcy-scqucnccd data set 

Offset Length Contents 

0 3 Reserved; unused 

3 1 Number of arguments (N) 

(N = 1 to 255) 

4+(N-l)(10+K) 4 Feedback RBA 

(K = key length) 

8+(N-l)(10-fK) 4 Feedback volume serial number 

(K = key length) 

14+(N-1)(10+K) K FuU key argument 

(K - key length) 

Entry-soqucnced data set or relative record data set 

OITsct Length Contents 

0 3 Reserved; unused 

3 1 Number of arguments (N) 

4+(N-l)(4) 4 Feedback RBA 

8 + (N-l)(I4) 6 Feedback volume serial number 

18 + (N-1)(14) 6 RBA/RRN argument 

The value for K is always 4 in an entry-sequenccd or relative record 
data set. Therefore, 10 + K is always 14 for these two types of data 
sets. The maximum number of arguments allowed is 255. 



Chapter 2. VSAM Macro Formats and Examples 57 



CNVTAD 



ECB" address 

specifies the address of an event control block (ECB) which you may 
specify. VSAM indicates in the ECB whether or not a request is 
complete. This parameter is optional. 

OFrCD = ({ADR|KEY) 
,{ASY|SYN) 
,{KEQ|KGE) 
,FKS) 

ADR is only valid for entiy-sequenced data sets. 

KEY is only valid for key-sequcnced data sets and relative record dat 
a sets. 

If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of ECBs (in 
standard WAIT list format) which you may use in place of the 
RPLECB field, 

GEN is not supported; if specified, it will give an error indication. 

AU other OPTGD subparameteFS- afe not applicable, and, if ^ecified, 
arc ignored with no error indications. 

For a given list of discrete arguments, CNVTAD returns the volume serial 
number (volser) and the RBA corresponding to each argument in the parameter 
list feedback area. The data portion of your VSAM data set is not referenced and 
need not be mounted even if the sequence set is embedded. 

For an entry-sequenced data set, the volser is returned, and the same RBA 
specified in the argument field is also returned. 

Note: The RBA retumed by CNVTAD in the case of a key-sequenced data set 
is not the exact RBA of the record. It is, in fact, an approximate value. (For 
data sets with the IMBED option, it is the RBA of the begiiming of the sequence 
set for the record's control area; for data sets with NOIMBED, it is the RBA of 
the record's control interval.) When passed to MNTACQ, these RBA values 
cause MNTACQ to stage the appropriate cylinders corresponding to the 
requested arguments ori^ally passed to CNVTAD. You should therefore use 
caution if you arc planning to use the RBAs obtained from CNVTAD for any 
purpose other than as input to MNTACQ. 

At the conclusion of this macro, the RPL is disconnected. Any positioning in 
effect prior to execution of this macro will be lost. You may have to reposition. 
Chained RPLs are not supported by CNVTAD. 
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DLVRP 



DLVRP Macro (Delete VSAM Resource Pool) 



The DLVRP macro has a standard form and an execute form. The standard 
form builds a parameter list and passes control to VSAM to delete the resource 
pool. The execute form is described in Appendix B, ^'List, Execute, and 
Generate Forms of Macros" on page 171. 

The format of the DLVRP macro is: 



DLVRP 



TYPE={LSR|GSR} 
|,MODE={24|3l}| 
I,SHRPOOL« {0\number}\ 



TVPE={LSR|GSR} 

specifies the type of resource pool to be deleted: local (I^SR) or global 
(GSR). When deleting an LSR pool, the number specified on the 
SI IR POOL parameter indicates which LSR pool is to be deleted. If both a 
data resource pool and an index resource pool have the same SIIRPOOL 
number, both will be deleted. The program that issues DLVRP 
TYPE'S GSR must be in supervisor state with protection key 0 to 7. 

MODE = {24131} 

specifics the format of the DLVRP parameter list that is to be generated. 



24 



specifics that a standard form (24-bit) parameter list address be built. 
This parameter list must reside below 1 6 mcgab>'tcs and contain the 
address of ACBs residing below 16 megabytes. The caller, however, 
may be above 16 megabytes. I'his is the default parameter list 
format. 



31 



specifies that a long form (31 -bit) parameter list address be built, 
lliis list can reside above or below 16 megabytes. This parameter 
value must be coded if the parameter tist resides above 16 megabytes 
or contains the address of a VSAM/VTAM ACB residing above 16 
megabytes. 

SHRPOOL- [0\number) 

specifies the identification number of the shared resource pool that is to be 
deleted. Valid only when TYPE" LSR is also specified, 'ilic DLVRP 
parameter list may reside above or below 16 megabytes. 

0 

specifies the shared pool with the identification of 0. This is the 
defauh LSR pool identification number. 

number 

specifies the shared pool with the identification of number where 
munber is a number firom 0 to 15. 
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DLVRP 



Example: DLVRP Macro 



This example shows how an LSR pool with a parameter list that may reside 
above 16 megabytes and identification number other than 0 is deleted. 

DELPOOL DLVRP TYPE=LSR, 
M0DE=31, 
SHRPOOIr=l 

The DLVRP parameters are: 

• TYPE specifies that an LSR pool is to be deleted. 

• MODE ~ 31 specifies the parameter list may reside above or below 16 
megabytes. 

• SHRPOOL specifies that the data resource pool and the index resource pool 
(if any) with the identication number of 1 are to be deleted. 
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ENDREQ 



ENDREQ Macro (Terminate a Request) 



The format of the ENDREQ macro is: 



\labei\ ENDREQ 



RPL'^ address 



where: 



label 



is 1 to 8 characters that provide a symbolic address for the ENDREQ 
macro. 



RVL'^ address 

specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 

Note: The ENDREQ macro must not be issued when records arc being loaded 
into a VSAM data set (load mode). ENDREQs issued while in load mode are 
ignored. 



Example: Release Positioning for Another Request 



In this example, the ENDREQ macro is used to cause VSAM to release 
exclusive control of a control interval containing a record. There are two request 
parameter lists, both of which require VSAM to have the ability to remember its 
position until VSAM is explicitly requested to forget its position. 



BLOCK ACB MACRF=(SEQ, 
DIR),STRN0=2 

SEQ RPL ACB=BLOCK, 

OPTCD=SEQ 

DIRUPD RPL ACB=BLOCK, 

OPTCD=(DIR,UPD) 



LOOP GET RPL=SEQ 

LTR 15,15 
BNZ ERROR 



VSAM must remember its 
position. 

VSAM must remember its 
position and maintain 
exclusive control imtil 
explicitly requested to 
forget it by PUT or 
ENDREQ. 

VSAM now remembers its 
position for this request 
only while it is 
processing the request. 



GET RPLsDIRUPD VSAM can remember its 

position for this request. 
LTR 15,15 The control interval will 

be placed in exclusive 
BNZ ERROR control until either 

ENDREQ or PUT UPD is 

issued. 
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ENDREQ 



Decide whether to update the record. 



FORGET 



ERROR 



B 

PUT 
LTR 


FORGET 

RPL=DIRUPD 

15,15 


No: do no^ uod.a'te the 
record. 

Yes; update the record, 
causing VSAM to forget its 
nositlon for DIRUP 


BNZ 


ERROR 




B 


LOOP 




ENDREQ RPL=DIRUPO 
LTR 15,15 


Cause VSAM to forget its 
position for DIRUPD. 
Release exclusive control. 


BNZ 


ERROR 




B 


LOOP 




XXX 




Request wasn't accepted or 
failed. 



The use of ENDREQ illustrated here causes VSAM to release exclusive control 
of the control interval for a record. When PUT is issued after a DIRUPD GET 
request, ENDREQ need not be issued, because PUT causes VSAiM to release 
exclusive control (the next DIRUPD GET doesn't depend on VSAM's 
remembering its position). Another result of ENDREQ is that current buffers 
arc written if they have been modified. 



To cause VSAM to give up its position associated with a chain of request 
parameter lists, specify the first request parameter list in the chain in your 
ENDREQ macro. 

ENDREQ can also be used to cancel an asynchronous request, rather than 
suspending processing with CHECK. 

Note: If you arc sharing subtasks or If you have issued an asynchronous request 
for access to a data set, you must issue a CHECK or an ENDREQ on all RPLs 
before you issue a CLOSE or CLOSE TYPE==T; otherwise, concurrent data set 
I/O activity will cause impredictable results during a close, in is adequate. 

Because VSAM remembers its position after a direct GET with OPTCD - UPD 
or LOC, if no PUT or ENDRIiQ follows, you can switch to sequential access 
and use the positioning for a GET. 
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ERASE 



ERASE Macro (Delete a Record) 



The format of the ERASE macro is: 



\iabei[ ERASE RPL - address 



where: 
iabel 

is 1 to 8 characters that provide a symbolic address for the ERASE macro. 
RPL^ address 

specifies the address of a request parameter list that defines the request. 
You may specify the address in register notation (using a re^pster from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A4ypc address constant. 

With ERASE processing of key-sequenced data sets, VSAM attempts to make 
the control interval available to the control area when the last record in the 
control interval is erased. 'ITius, kcy-scquenced data set control intervals can be 
reused for new records whose keys fall anywhere within the control area's range 
of keys. You may suppress the process of reclaiming the control interval by 
setting RPLNOCIR in the RPL used for ERASE. The high key control interval 
of a control area is never reclaimed. 



Example 1: Keyed- Direct Deletion 



In this example, GET and ERASE macros are used to retrieve and delete records. 
Not every record retrieved for deletion is deleted, llie search argument is a full 
key (5 bytes), compared equal. 



DELETE ACB 



LIST 



RPL 



MACRF=(KEy,DIR, 
ODT) 

ACB=DELETE, 

AREA=¥ORK, 

AREALEN=:50, 

ARG=KEYFIELD, 

OPTCD=(KEY,DIR, 

SYN,UPD, 

MVE.FKS, 

KEQ) 



UPD indicates deletion. 



LOOP HVC KEYFIELD, source Search argument for 

retrieval, from a table 
or transaction record. 

GET RPL=LIST 
LTR 15,15 
BNZ ERROR 
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ERASE 



Decide whether to delete the record. 
BE LOOP 
ERASE RPL=LIST 
LTR 15,15 



No; retrieve the next record. 
Yes; delete the record. 



BNZ 
B 



ERROR 



WORK DS 
KEYFIELO OS 



ERROR 
LOOP 

CL50 
CL5 



Request was not accepted, or 
failed. 

Examine the data record here. 
Search argument. 



When you retrieve a record for deletion (OI*TCD= UPD, same as retrieval for 
update), VSAM is positioned at the record retrieved, in anticipation of a 
succeeding ERASE (or PUT) request for that record. You arc not required to 
issue such a request, though. Another GUT request nullifies any previous 
positioning for deletion or update. 

Keyed-sequential retrieval for deletion varies from direct in not using a search 
argument (except for possible use of the POINT macro). Skip-sequential 
retrieval for deletion (OI*TCD = (SKP,UPD)) has the same effect as direct, but it 
is faster or slower depending on the number of control intervals separating the 
records being retrieved. 



Example 2: Addrcsscd-Scqucntial Deletion 



In this example, the ERASE macro is used to delete records from a 
key-scquenced data set. Not every record retrieved for deletion is deleted. 
Skipping is effected by the POINT macro. 



DELETE ACB 



REQUEST RPL 



MACRF=(ADR,SEQ, 
OUT) 

ACB=DELETE, 

AREA=WORK, 

AREALEN=100, 

ARG=ADDR, 

OPTCD=(ADR,SEQ, 

ASY 

updImve) 



UPD indicates deletion. 



LOOP . . . Decide whether you need to 

skip to another position 
forward or backward) . 

B RETRIEVE No; bypass the POINT. 

MVC ADDR, source Yes; move search argument 

for POINT into 
search -argument field. 
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ERASE 





POINT 


RPLfREQUEST 




LTR 


15,15 




BNZ 


ERROR 




CHECK 


RPIr^REQUEST 




LTR 


15,15 




BNZ 


ERROR 


RETRIEVE GET 


RPIr=REQUEST 




LTR 


15,15 




BNZ 


ERROR 




CHECK 


RPIr=REQUEST 




LTR 


15,15 




BNZ 


ERROR 


Decide whether to delete the record. 




BE 


LOOP 




ERASE 


RPL=REQUEST 




LTR 


15,15 




BNZ ' 


ERROR 




CHECK 


RPL=REQUEST 




LTR 


15,15 




BNZ 


ERROR 




B 


LOOP 


ERROR 


• • • 
• 




ADDR 


DS 


F 



Position VSAM to the 
record to be retrieved 
next. 



No; skip ERASE and CHECK. 
Yes; delete the record. 



WORK 



DS 



CLIOO 



Request was not accepted, 
or failed. 



RBA search argument for 

POINT. 

Work area. 



Addressed deletion is allowed only for a kcy-sequcnccd data set. The records of 
an entiy-sequenced data set are fixed. When records are deleted using addressed 
deletion from a key-scquenccd data set, the index is not updated. 
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EXLST 

EXLST Macro (Generate an Exit List at Assembly Time) 



The fonnat of the EXLST macro is: 



\labeli 


EXLST 


lAM-VSAMI 






|,EODAD » {address\,A\^\m)\ 






llOPlD = (address)] 






MRNAD = iaddress\A\M,U)\ 






|,LERAD - (address\,A\MX\)\ 






|,SYNAD = (a^/^/rejj|,A|N|l,L|)| 






|,UPAD > (a</Jrtfjj|,A|N|(,L|)l 



Values for OXLST macro subparamctcrs can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-type address constants. 

Note: See Data Facility Product: Customization for the factors that determine 
the addressing mode and the parameter list residency mode set when the exit 
routine gets control. 

labei 

is 1 to 8 characters that provide a symboUc address for the exit list that is 
estab^shed. 

AM = VSAM 

specifies that the access method using the control block is VSAM. 

EODXD ^iaddress\,\\MM 
lOVlD^ (address) 
JRNAI) = (a</i/rejj|,A|N|[,LD 
LERAD = (address{,A\7<\l\]) 
SYN AD = (a«/drejjf ,A|N||,LD 
UPAD = (addresslA\^\lA\) 

specify that you are supplying a routine for the exit specified. 

For more information about user exit routines, see Data Facility Product: 
Customization. 

The exits and values that can be specified for these routines are: 
EODAD 

specifies that an exit is provided for special processing wheii the end 
of a data set is reached by sequential access. 

lOPID 

specifies that an I/O prevention identifier is provided to terminate I/O 
and prevent new I/O from being started for the data sets associated 
with the identifier. When the lOPID address is specified, the 
identifier is always assumed to be active. 
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EXLST 



JRNAD 

specifies that an exit is provided for journalizing transactions as you 
process data records. 

LERAD 

specifies that an exit is provided for analyzing logical errors. 
SYNAD 

specifics that an exit is provided for analyzing physical errors. 
UPAD 

specifies that an exit is provided for user processing during a VSAM 
request. The GENCB, MODCB, SIIOWCB, and TESTCB macros 
do not support the UPAD user exit routine. 

address 

is the address of a user-supplied e;dt routine or an I/O prevention 
identifier. The address must immediately follow the equal sign. 



A|N 



specifics that the exit routine is active (A) or not active (N). 
does not enter a routine whose exit is marked not active. 



VSAM 



Examine: EXLST Macro 



specifics that the address is that of an 8-by1e field that contains the 
name of an exit routine in a partitioned data set that is identified by a 
JOBLIB or STliPLIB DD statement or in SYSl.LINKLIB. VSAM 
is to load the exit routine for exit processing. If L is omitted, the 
address gives the entry point of the exit routine in virtual storage, and 
the exit routine is entered in the addressing mode of the VSA.M caller. 



In this example, an EX LSI' macro is used to identify exit routines that are 
provided for analyzing logical and physical errors. The label, EXITS, of the 
EXLST macro is used in an ACB or GENCB macro that generates an access 
method control block to associate the exit list with an access method control 
block. The exit list generated by this example is built when the program is 
dissembled. 

EXITS EXLST EODAD=(ENDUP,N) , EXITS gives symbolic 

LERAD-LOGICAL, address of the exit list. 
SYNAD=(ROUTNAME,L) 



ENDUP 
LOGICAL 
ROUTNAME DC 



C* PHYSICAL" 



EODAD routine. 

LERAD routine. 

Pad shorter names with 
blanks: C'SYN'or CLS'SYN' 



The EXLST macro's parameters are: 



• EODAD specifies that the end-of-data routine is located at ENDUP and is 
not active. 
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EXLST 

• LERAD specifies that the logical error routine is located at LOGICAL and 
active. 

• SYNAD specifies that the physical error routine's name is located at 
ROUTNAME. 
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GENCB~ACB 



i GENCB Macro (Generate an Access Method Control Block at 
I Execution Time) 

The format of the GENCB macro used to generate an access method control 
block is: 



[labe/i 


GENCB 


BLK = ACB 






l,AM = VSAMI 






lBSTRNO = number] 






inmKD^' number] 






|,BUFNI = number] 






IBVFSV=- number] 






|,CATALOG= YESINOI 






lCO\n¥:S = number] 






|,CRA = SCRA|UCRA| 






i,DDN AME = ddname] 






|,EXLST= address] 






ILEJ^GTH'^ number] 






lXOC = BELOVV|ANY| 






|,MACRF = (IADR|I,CNV||,KEY| 






|,CFX|NFX| 






|,I>DN|DSN| 






|,DFR|NDF| 






LDIR||,SEOIi,SKl>l 






|,ICI|NCI| 






MNII,OLT| 






|,NLS|SISI 






|,NRM|A1X| 






LNRSIRSTI 






|,NSRtIi>R|GSRi 






|,M)B|UBF1)I 






i,MAREA^ a^^msl 






|,MLEN = number] 






IV ASS\M)^ address] 






LRMODE3I = (ALLIBUFFICBINONE)! 






|,SHRPOOL= {0\number}] 






l^TRNO^ number] 






IV/AREA^ address] 



I Note: The RMODE parameter replaces the AM0DE31 subparamctcr used in 

I previous releases. 

The subparametcrs of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-type address 
I constants, and as indirect S-type address constants. Appendix C, "Operand 

I Notation" on page 181, further defmes these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the GENCB macro. 



Chapter 2. VSAM Macro Formats and Examples 69 



GENCB-ACB 



BLK^ACB 

specifies that you are generating an access method control block. 
AM-VSAM 

specifies that the access method using this control block is VSAM. 

BSTRSO^ number 

specifies the number of strings initially allocated for access to the base 
cluster of a path. The defauU is STRNO. BSTRNO is ignored if the 
object being opened is not a path. If the number specified for BSTRNO is 
insufficient, VSAM will dynamically extend the number of strings as needed 
for the access to the base cluster. BSTRNO can also influence 
performance. The VSAM control blocks for the set of strings specified by 
BSTRNO are allocated on contiguous virtual storage, whereas this is not 
guaranteed for the strings allocated by dynamic extension. 

nVF^D-' number 

specifics the number of I/O buffers VSAM is to use for transmitting data 
between virtual and auxiliary storage. A buffer is the size of a control 
interval in the data component. The minimum number you may specify is 
1 plus the number specified for STRNO (if you omit STRNO, BUFND 
must be at least 2, because the default for S TRNO is 1). 'Ilic number can 
be supplied by way of the JCL DD AMP parameter as well as by way of 
the macro. Tfie default is the minimum number required. A larger number 
for BUFND can improve the performance of sequential access. 

BWSl — number 

specifics the number of I/O buffers VSAM is to use for transmitting index 
entries between virtual and auxiliary storage for keyed access. A buffer is 
the size of a control interval in the index, llie minimum number is the 
number specified for STRNO (if you omit STRNO, BUFNI must be at 
least 1, because the default for S TRNO is 1). You can supply the number 
by way of the JCL DD AMP parameter as well as by way of the macro, 
llie default is the minimum number required. A larger number for BUFNI 
can improve the performance of keyed-direct retrieval. 

BUFSP-/iwm6er 

specifies the maximum number of bytes of virtual storage to be used for the 
data and index I/O buffers. VSAM gets the storage in your program's 
address space. If you specify less than the amount of space that was 
specified in the BUFFFRSPACE parameter of the DFFINF command 
when the data set was defined, VSAM overrides your BUI*SP specification 
upward to the value specified in BUFFERSPACE. (BUFFFRSPACE, by 
definition, is the least amount of virtual storage that will ever be provided 
for I/O buffers.) You can supply BUFSP by way of the JCL DD AMP 
parameter as well as by way of the macro. If you don't specify BUFSP in 
either place, the amount of storage used for buffer allocation is the largest 
of: 

• The amount specified in the catalog (BUFFERSPACE), 

• The amount determined from BUFND and BUFNI, or 
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• The minimum storage required to process the data set with its specified 
processing options 

If BUFSP is specified and the amount is smaller than the minimum 
amount of storage required to process the data set, VSAM carmot open the 
data set. 

A valid BUFSP amount takes precedence over the amount called for by 
BUFND and BUFNI. If the BUFSP amount is greater than the amount 
called for by BUFND and BUFNI, the extra space is allocated as follows: 

• When MACRF indicates direct access only, additional index buffers are 
allocated. 

• When MACRF indicates sequential access, one additional index buffer 
and as many data buffers as possible are allocated. 

If the BUFSP amount is less than the amount called for by BUF^ND and 
BUFNI, the number of data and index buffers is decreased as follows: 

• When MACRF indicates direct access only, the number of data buffers 
is decreased to not less than the minimum number, llicn, if required, 
the number of index buffers is decreased until the amount called for by 
BUFND and BUFNI complies with the BUI-SP amount. 

• When MACRF indicates sequential access, the number of index buffers 
is decreased to not less than 1 more than the minimum number. Then, 
if required, the number of data buffers is decreased to not less than the 
minimum number. If still required, 1 more is subtracted from the 
number of index buffers. 

• Neither the number of data buffers nor the number of index buffers is 
decreased to less than the minimum number. 

if the index doesn't exist or isn't bemg opened, only BUFND, and not 
BUFNI, enters into these calculations. 

CATALOG = YES|NO 

specifics whether a catalog is being opened as a catalog (YfiS) or as a data 
set (NO). When NO is coded (or taken as the default), you can process the 
catdog with request macros (GET, PUT, etc.). To open a 
password-protected catalog for processing with VSAM macros, you must 
supply its master password. When CATAIiDG^^ YHS is coded, the catalog 
must be processed with an SVC designed for that purpose. (Access method 
services, for example, processes catalogs with SVC 26.) The request macros 
are invalid for processing a catalog "as a catalog.*' VSAM users should alter 
the contents of a catalog only by access method services commands. 

•COPIES «/iMm^r 

specifics the number of copies of the access method control block VSAM is 
to generate. All the copies are identical. You can use MODCB to tailor 
each one for the data set and processing you want for it. MODCB is 
described later in this chapter. 
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CRA = SCRA|UCRA 

specifies that a catalog recovery area is to be opened and that the control 
blocks are to be built in either system storage (SCR A) or user storage 
(UCRA). If you specify SCRA and issue record management requests, you 
must operate in key 0. If you specify UCRA, you must be authorized by 
the system and you must supply the master password of the master catalog. 

DDNAME'' ddname 

is 1 to S characters that identify the data set that you want to process by 
specifying the JCL DD statement for the data set. You may omit 
DDNAME and provide it by way of the MODCB macro before opening 
the data set. MODCB is described later in this chapter. 

EXLST = address 

specifics the address of a list of addresses of exit routines that you are 
providing. The list is established by the EXLST or GENCB macro. If you 
use the EXLST macro, you can specify its label here as the address of the 
exit list. If you use GENCB, you can specify the address returned by 
GENCB in register 1. Omitting this parameter indicates that you have no 
exit routines. Exit routines are described in the chapter "User- Written Exit 
Routtncs" in Data Facility Product: Customization. 

LENGTH = rt«m6er 

specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the access method control block(s). (Sec the WAREA 
parameter.) When the LENGTH value is specified, it cannot exceed 65535 
(X'FFFF*). 

LOC = BELOW|ANY 

BELOW 

specifies that VSAM is to construct an ACB in an area of virtual 
stora^ below 16 megabytes at execution time. This is the default. 

ANY 

specifies that VSAM is to construct an ACB in an area of virtual 
storage above 16 megabytes, if possible, at execution time. 

MACRF = (lADRILCNVIL KEYI 
f.CFXI NFXI 
I. DDN IDSNI 
rPFRINDFI 
i,DIRil, SEOB ,SKPI 
|,ICI|NCI| 
|,IN|I,OUTl 
LNISISlSi 
[,NRM|AIX| 
LNRSIRSn 
|,NSR|LSR|GSR| 
|,NUBIUBFD 

specifies the kind(s) of processing you will do with the data set. The 
subparameters must be meaningfiil for the data set. For example, if you 
specify keyed access for an entry-sequenced data set, you cannot open the 
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data set. You must specify all the types of access you're going to use, 
whether you use them concurrently or by switching from one to the other. 
The subparamcters are shown in Figure 12 on page 38. They are arranged 
in groups, and each group has a default value (indicated by underlining). 
You may specify subparamcters in any order. You may specify both ADR 
and KEY to process a key-sequenccd data set. You may specify both DIR 
and SEQ; with keyed access, you may specify SKP as well. If you specify 
OUT and want merely to retrieve some records as well as update, delete, or 
insert others, you need not also specify IN. 

Note: The RMODE31 parameter replaces the AMODE31 subparametcr 
used in previous releases. 

MAREA » address 

specifics the address of an optional OPEN/CLOSE or TYPL = T option 
(CLOSE macro) message area. 

MLEN = number 

specifics the length of an optional OPEN/CLOSE or TYPE=T option 
(CLOSE macro) message area. 

VXSSWD^ address 

specifies the address of a field that contains the highest-level password 
required for the type(s) of access indicated by the MACRF parameter. The 
first byte of the field contains the length (in binary) of the password 
(maximum of 8 bytes). Zero indicates that no password is supplied. If the 
data set is i>assword protected and you don't supply a required password in 
the access method control block, VSAM may give the console operator the 
opportunity to supply it when you open the data set. 

R.M ODE3I = lALLlBUFFICBi NONEI 

specifies where VSAM OPEN is to obtain virtual storage (above or below 
16 megabytes) for control blocks and I/O buffers. 

The values specified by the RM0DE31 parameter only have an effect on 
VSAM at the setting just before an OPEN is issued. At all other times, 
chang^ig these values has no effect on the residency of the control blocks 
and I/O buffers. 

The virtual storage location of the ACB is independent of the RM0DE31 
parameter. An ACB may reside cither above or below 16 megabytes. 

ALL 

both VSAM control blocks and I/O buffers are to be obtained above 
16 megabytes. 

BUFF 

only VSAM I/O buffers are to be obt^ed above 16 megabytes. 

CB 

only VSAM control blocks are to be obtained above 16 megabytes. 
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NONE 

both VSAM control blocks and I/O bufifcrs are to be obtained below 
16 megabytes. This is the default. 

SHRPOOL-{/TumM2) 

specifics the identification number of the resource pool to be used for LSR 
processing. The default is SIIRPOOL=0. 

STRNO^ number 

specifics the number of requests requiring concurrent data set positioning 
VSAM is to be prepared to handle. A request is dcfmcd by a given request 
parameter list or chain of request parameter lists. See "RPL Macro 
(Generate a Request Parameter List at Assembly Time)" on page 126 and 
"GENCB Macro (Generate a Request Parameter List at Execution Time)" 
on page 80 for information on request parameter lists. 

\y AREA-' address 

specifics the address of an area in which to generate the access method 
control block(s). 



i The area must begin on a fuUword boundary. 

f This parameter is paired with the LENGTH parameter. You must supply 

I the LENG TH parameter if you specify an area address. 

I Note: If you do not specify an area in which the access method control 

I block is to be generated, VSAM obtains virtual storage space for the area 

I (as specified by the LOG = keyword). VSAM returns the address of the 

I area containing the control block(s) in rc^ster 1 and the length of the area 

in register 0. You can find out the length of each control block by dividing 
the length of the area by the number of copies. The address of each control 
block can then be calculated by this offset from the address in register 1. 
You can fmd the length of an access method control block with the 
SHOVVCB macro. 



If you arc generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH parameters) for them enables you to 
address all of them with one base re^ster and to avoid repetitive requests 
for virtual storagp. . 
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Example: GENCB Macro (Generate an Access Method Control Block) 



In this example, a GENCB macro is used to identify a data set to be opened and 
to specify the types of processing to be performed. This example specifics that 
the space for the control block be obtained above 16 megabytes. The access 
method control block generated by this example is built when the program is 
executed. 



GENCB 



GENCB 



ST 



ACBADDR DS 



FIELD 



DC 



BLK=ACB,AM=VSAM, 

BUFND=4,BUFNI=3, 

BUFSP=*19456, 

DDNAME=DATASETS, 

EXLST=EXITS, 

LOC=ANY, 

MACRF=(KEy,DIR, 

SEQ,OUT), 

PASSWD=FIELD, 

RM0DE31-ALL, 

STRN0=2 

1,ACBADDR 



FL1*6*,C*CHANGE* 



One copy generated; VSAM 
gets the storage for it, 
because the WAREA LENGTH 
parameters have been 
omitted. 



Save the address of the 
access method control 
block. 

The address of the 
access method control 
block is saved in 
ACBADDR. 

CHANGE, the password, has 
6 characters. 



'Ilie GI.:NCB macro's parameters are: 

• BUFND specifics four I/O buffers for data; BUFNI specifics three I/O 
buffers for index entries; and BUFSP specifics 194S6 bytes of buffer space, 
enough space to accommodate control intervals of data that are 4096 b>tes 
and of index entries that are 1024 bytes. 

• DDNAME specifies that this access method control block is associated with 
a DD statement named DATASETS. 

• EXLST specifics that the exit list assodated with this access method control 
block is named EXI TS. 

• LOC specifics that VSAM obtain virtual stora^ for the ACB from an area 
that may be above 16 mc^bytes. 

• MACRF specifies keyed direct and keyed sequential processing for both 
insertion and update. 

• PASSVVD specifies the location, FIELD, of the password provided. 

• RM0DE31 specifics that VSAM obtain storage for the VSAM control 
blocks and I/O buffers in an area above 16 megabytes when the ACB is 
opened. 

• STRNO specifies that two requests will require concurrent positioning. 
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GENCB Macro (Generate an Exit List at Execution Time) 



The foimat of the GENCB macro used to generate an exit list is: 



[iabeli 


GENCB 


BLK = EXLST 






UM = VSAiVII 






I,EODAD = (addres4M>^\m)\ 






MRNAD = (address\,A\MX\)\ 






|,L£RAD « {address\,A\?s\lLD\ 






I,SYNAD = (address{,A\\\lL\)\ 






ICOPIES^ number] " 






I,LENGTH = /iww6er| 






I.LOC- BELOW! ANYI 






IWAREA" address] 



The parameters of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-typc address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

Note: See Data Facility Product: Customization for the factors that determine 
the addressing mode and the parameter list residency mode set when the exit 
routine gets control. 

label 

is 1 to 8 characters that provids a symbolic address for the GENCB macro. 

BLK-EXLST 

specifies that you are generating an exit list. 

AM=VSAM 

specifies that the access method using this control block is VSAM. 

|,£ODAD - (address[,A\l^]lLd\ 
MRNAD = {addresslA\^\m)\ 
|,LERAD " (aJ^rej^.A|N||,L|)| 
I3YNAD - iaddres4^\MM)\ 

specify that you are supplying a routine for the exit named. 

For more information about user exit routines, see Data facility Product: 
Customization. 

If none of these user exit routines is specified, VSAM generates an exit list 
with inactive entries for all the exits. The exits and values that can be 
specified for them are: 

EODAD 

specifies that an exit is provided for special processing when the end 
of a data set is reached by sequential access. 
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JRNAD 

specifies that an exit is provided for joumaling as you process data 
records. 

LERAD 

specifies that an exit is provided for analyzing logical errors. 
SYNAD 

specifics that an exit is provided for analyzing physical errors. 
address 

is the address of a user-supplied exit routine. The address must 
immediately follow the equal sign. 

A|N 

specifies that the exit routine is active (A) or not active (N). VSAM 
does not enter a routine whose exit is marked not active. 

L 

specifies that the address is that of an 8-byte field that contains the 
name of an exit routine in a partitioned data set that is identified by a 
JOBLIB or STBPLIB DD statement or in SYSl.LINKLIB. VSAM 
is to load the exit routine for exit processing. If L is omitted, the 
address gives the entry point of the exit routine in virtual storage, and 
the exit routine is entered in the addressing mode of the VSAM caller. 
L may precede or follow the A or N specification. 

COVWS^ number 

specifies the number of copies of the exit list you want generated. GENCB 
generates as many copies as you specify (default is 1) when your program is 
executed. All copies are the same. You can use MODCB to change some 
or all of the addresses in a list. (MODCB is described later in this chapter.) 

LENGTH " number 

specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the exit list(s). (See the WAREA parameter.) When 
the LENGTH value is specified, it cannot exceed 65535 (X * FFFF * ). 

LOC = BELOW|ANY 

BELOW 

specifies that VSAM is to construct an exit list in an area below 16 
megabytes at execution time. This is the default value. 

ANY 

specifies that VSAM is to construct an exit list in an area above 16 
megabytes, if possible, at execution time. 

yfASEk^ address 

specifies the address of an area in which the exit list(s) is to be generated. 

The area must begin on a fiiUword boundary. 
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This parameter is paired with the LENGTH parameter, which must be 
given if you speciify an area address. 

Note: If you did not specify an area in which the exit list is to be 
generated, VSAM obtains virtual storage space for the area (as specified by 
the LOC = keyword). VSAM returns the address of the area in which the 
exit lists(s) is to be generated in register 1, and the length of the area in 
rejpster 0. You can find the length of each exit list by dividing the length of 
the area by the number of copies. The address of each exit list can then be 
calculated by this offset from the address in register 1. You can find the 
length of an exit list with the SHOVVCB macro, described under 
"SI IOWCB Macro (Display Fields of an Exit List)" on page 139. 

If you are generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENG TH) for them enables you to address all of 
them with one base register and to avoid repetitive requests for virtual 
storage. 

Example: GENCB Macro (Generate an Exit List) 

In this example, a GENCB macfo is used to generate an exit list when the 



program is executed. 


EXITS 


GENCB 


BLK=EXLST, 

EOnAD*(EOU,PO, 
LERAD=LOGICAL, 
SYNAD=(ERROR, 
A,L) 




LTR 


15,15 




BNZ 


ERROR 




ST 


1,EXLSTADR 


EOO 


EQU 


•k 


LOGICAL 


EQU 


•k 


ERROR 


DC 


C* PHYSICAL* 


EXLSTAOR DS 


F 



Address of the exit list is saved. 

EOOAD routine. 

LERAD routine. 

Name of the SYNAO module. 

Save area for exit -list address. 



The GENCB macro's parameters arc: 

• BLK specifies that an exit list is to be generated. 

• EODAD specifics that the end-of-data routine is located at EOD and is not 
active. 



• LERAD specifies that the lo^cal error routine is located at LOGICAL; 

because neither A nor N is specified, the LERAD routine is marked active by 
default. 



• SYNAD specifies that the physical error routine's name is located at 
ERROR. 
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Because no area was specified in which the exit list was to be. generated, VSAM 
obtained virtual storage for the exit list and returned the address in register 1. 
Immediately after the GENCB macro, the address of the exit list, contained in 
register 1, is moved to EXLSTADR. EXLSTADR may be specified in a 
GENCB macro that generates an access method control block or in a MODCB, 
SHOWCB, or TESTCB macro that modifies, displays, or tests fields in an exit 
list. 
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I GENCB Macro (Generate a Request Parameter List at Execution 
I Time) 



The format of the GENCB macro used to generate a request parameter list is: 



1 1 f M 

\labei\ 


GENCB 


BLK = RPL 






(,ACB = address] 






lAM = VSAMI 






(,AR£A address] 






|,ARLALLN = number\ 






1,ARG = address] 






j,COPIES = number] 






(,ECB « address] 






(,KEYLEN = number] 






j,LENGTII = /M/m6e/1 






IXOC = BELOWl ANYI 






|,MSGAREA = address] 






i,MSGLEN = number] 






|,NXTRPL = address] 












I.DIRISEOISKPI 






},ARl>^LRKH 






|,F\VDjB\VD| 






|,ASY|SYN| 






|,NSP|NUP|UPD| 






|,KE(2|KCE| 






|,FKS|GEN| 






|,LOC|[VIVEI)I 






IRECLES^ number] 






I'lRASSlD''^ number] 






IWAREA'' address] 



The parameters of the GENCB macro can be expressed as absolute numeric 
expressions, as character string, as codes, as expressions that generate vaUd 
relocatable A-type address constants, in register notation, as S-type address 
I constants, and as indirect S-type address constants. Appendix C, "Operand 

I Notation" on page 181 further defines these operand expressions. 

The parameters of the GENCB macro to generate a request parameter list are 
optional in some cases, but required in others. It is not necessary to omit 
parameters that are not required for a request; they are ignored. Thus, for 
example, if you switch from direct to sequential retrieval with a request parameter 
list, you don't have to zero out the address of the field containing the search 
argument (ARG = address). 

label 

is 1 to 8 characters that provide a symbolic address for the GENCB macro. 
For addressing lists generated by GENCB, see the discussion of the 
COPIES parameter. 
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BLK=^RPL 

specifies that you are generating a request parameter list. 
ACB=' address 

specifies the address of the access method control block that identifies the 
data set to which access will be requested. If you omit this parameter, you 
must issue MODCB to specify the address of the acceto method control 
block before you issue a request. (MODCB is described later in this 
chapter.) 

AM = VSAM 

specifies that the access method u^g this control block is VSAM. 
AREA «= address 

specifics the address of a work area to and from which VSAM moves a data 
record if you request it to do so (with the RPL parameter 
OPTCD= MVE). If you request that records be processed in the I/O 
buffer (OPTCD= LOC), VSAM puts into this work area the address of a 
data record within the I/O buffer. 

AREALEN = /M/w6er 

specifics the length, in bytes, of the work area whose address is specified by 
the AREA parameter. Its minimum for OPTCD= MVE is the size of a 
data record (or the largest data record, for a data set with records of variable 
length). For OPTCD = LOC, the area should be 4 bytes to cont^n the 
address of a data record within the I/O buffer. 

ARC = address 

specifies the address of a field that contains the search argument for direct 
retrieval, skip-sequential retrieval, and positioning. For a relative record 
data set, the ARG field must be 4 bytes long. For direct or skip-sequential 
processing, this field cont^s your search argument, a relative record 
number. For sequential processing (OPTCD- (KEY,SEQ)), the 4 bytes 
arc required for VSAM 4o return the^edback ilRN. For keyed access 
(OPTCD= KEY), the search argument is a full or generic key; for 
addressed access (OPTCD»=ADR), it is an RBA. If you specify a generic 
key (OPTCD=GEN), you must also specify in the KEYLEN parameter 
how many of the bytes of the full key you are using for the generic key. 

COVIES^ number 

specifies the number of copies of the request parameter list you want 
generated. GENCB generates as many copies as you specify (default is 1) 
when your program is executed. 

The copies of a request parameter list can be used to: 

• Chain lists together to ^un access to many records ^th one request 

• Define many requests to gain access to many parts of a data set 
concurrently 

All copies generated are identical; you must use MODCB to tailor them to 
specific requests. MODCB is described in this chapter. 
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ECB^* address 

specifies the address of an event control block (ECB) that you may supply. 
VSAM indicates in the ECB whether a request is complete or not (using 
standard completion codes, which are described in Data Areas). You can 
use the ECB to determine that an asynchronous request is complete before 
issuing a CHECK macro. This parameter is always optional. 

KEYLEN = /lumber 

specifies the length, in bytes, of the generic key (OPTCD = GEN) you are 
using for a search argument (given in the field addressed by the ARG 
parameter). This parameter is required with a search argument that is a 
generic key. The number can be 1 through 255. For full-key searches, 
VSAM knows the key length, which is taken from the catalog dcfmition of 
the data set when you open the data set. 

LENGTH = number 

specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the request parameter list(s). (Sec the WAREA 
parameter.) When the LENGTH value is specified, it cannot exceed 65535 
(X'FFFF*). 

You can find out how long a request parameter list is with the SIIOWCB 
macro, described later in this chapter. 

LOC = BELOW|ANY 

BELOW 

specifies that storage for the RPL be obtained from virtual storage 
below 16 megabytes. 'ITiis is the default value. 

ANY 

specifies that storage be obtained from virtual storage above 16 
megabytes if possible. 

MSCwAREA^ address 

specifies the address of an area that you are supplying for VSAM to send 
you a message m case of a physical error. (The format of a physical error 
message is given under "Physical Errors'* in the chapter "Request 
Macros.") 

MSGLE^i^ number 

specifics the size, in bytes, of the message area indicated in the MSGAREA 
parameter. The size of a message is 128 bytes; if you provide less than 128 
bytes, no message is returned to your program. This parameter is required 
when MSGAREA is coded. 
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I^XTRPL' address 

specifies the address of the next request parameter list in a chain. Omit this 
parameter from the macro that generates the only or last list in the chain. 
When you issue a request that is defined by a chain of request parameter 
lists, indicate in the request macro the address of the first parameter list in 
the chain. A single request macro can be defined by multiple request 
parameter lists, such that a GET, for example, can cause VSAM to retrieve 
two or more records. 

OPTCD = ((ADR|CNV|KEY| 
LDIRISKQISKIM 
|,ARD|LRD| 
|,FWI)|BWDJ 
I,ASVjSYN| 
|,NSP|NUP|UPD| 
LKKQIKGEI 
|,FKS|GEN| 
iXOC lMVEl) 

specifics the subparamctcrs that govern the request dcfmcd by the request 
parameter list. Each group of subparameters has a default; subparamctcrs 
arc shown in Figure 13 on page 128 with defaults underlined. Only one 
subparamctcr /rom each group is effective for a request. Some requests do 
not require an subparamctcr from all of the groups to be specified. The 
groups that are not required are ignored; thus, you can use the same request 
parameter list for a combination of requests (GBT, PUT, POINT, for 
example) without zeroing out the inapplicable subparameters each time you 
go from one request to another. 

RECLE^^ number 

specifies the length, in bytes, of a data record being stored. If the records 
you are storing arc all the same length, you will not need to change 
RECLliN after you set it. This parameter is required for PUT requests. 
For GET requests, VSAM puts the length of the record retrieved in this 
field in the request parameter list. It wHlbe there if you update and store 
the record. 

TRANSID -m/m^r 

specifics a number that relates modified buffers in a buffer pool. Use in 
sharcd resource applications and a description arc in "Sharing Resources" 
in VSAM Administration Guide. 

\y AREA'' address 

specifics the address of an area in which the request parameter list(s) is to 
be generated. 

The area must be^ on a fullword boundary. 

This parameter is paired with the LENGTH parameter, which must be 
given if you specify an area address. 

Note: If you did not specify an area in which the request parameter list is 
to be generated, VSAM obtains virtual storage space for the area (as 
specified by the LOC = keyword). VSAM returns the address of the area in 
which the request parameter list(s) is generated in re^er 1, and. the length 
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of the area in register 0. You can find the length of each list by dividing the 
length of the area by the number of copies. You can then calculate the 
address of each list by using the length of each list as an offset. 

If you are generating control blocks by issuing several GENCBs, specifying 
an area (WARE A and LENGTH parameters) for them enables you to 
address all of them with one base register and to avoid repetitive requests 
for virtual storage. 



Building a Chain of Request Parameter Lists 



When GENCB is used to build a chmn of request parameter lists, the request 
parameter lists may be chained using only GENCB macros or using GENCB and 
MODCB macros together. When only GENCB is used, the request parameter 
lists are created in reverse order, as follows: 

SECOND GENCB BLK=RPL 

LR 2,1 
FIRST GENCB BLK=RPL,NXTRPL=:(2) 



SECOND GENCB creates the second request parameter list, which makes its 
address available for the first request parameter list. 'Ilie address of the request 
parameter list is returned in register 1 and is loaded into register 2. FIRST 
GENCB creates the first request parameter list and supplies the address of the 
ficjct request parameter list using register notation. GENCB and \tOOC& 
macros may be used together to create a chain of request parameter lists, as 
follows: 



GENCB BLK=RPL,C0PIES=2 

LR 2,0 

SRL 2,1 

LR 3,1 

LA 4,0(2,3) 

MODCB RPL=( 3 ) , NXTRPL=( 4) 



The GENCB macro creates two request parameter lists. The length of the 
parameter lists is retumed in register 0 and loaded into register 2. The address of 
the area in which the lists were created (and, therefore, the address of the fust 
one) is retumed in register 1 and loaded into register 3. The SRL statement 
divides the total length of the area (register 2) by 2. The LA statement loads the 
address of the second request parameter list into register 4. The MODCB macro 
modifies the first request parameter list (register 3) by supplying the address of the 
second request parameter list (register 4) in the NXTRPL parameter. 

Each request parameter list in a chain should have the same OPTCD 
subparameters. Having different subparameters may cause logical errors. You 
can't chaui request parameter lists for updating or deleting records— only for 
retrieving records or storing new records. You can't process records in the I/O 
buffer with chained request parameter Usts. (OPTCD - UPD and LOC are 
invalid for chained request parameter lists.) 
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Example: GENCB Macro (Generate a Request Parameter List) 

In this example, a GENCB macro is used to generate a request parameter list. 

ACCESS GENCB BLK=RPL, 

ACB=ACCESS, 

AM=VSAM, 

AREA=WORK, 

AREALEN=125, 

ARG=SEARCH, 

LOC=ANY, 

MS6AREA=MESSAGE, 

HS6LEN=128, 

OPTCD=(SKP,UPD) 



ACCESS ACB 

WORK DS 

SEARCH DS 

MESSAGE DS 



MACRF=(SKP,OUT) 

CL125 

CL8 

CL128 



The GENCB macro's parameters are: 

BL.K specifies that a request parameter list is to be generated. 

ACB specifies that the request parameter list is associated with a data set and 
processing options identified by ACCESS. 

AREA and AREALEN specify a 12S-byte work area to be used for 
processing records. 

ARG speciiies the address of the search argument. 

LOC specifics that VSAM obtain storage for the request parameter list in an 
area above 16 megabytes. 

MSGAREA and MSGLEN specify a 128-byte area to be used for 
physical-error messages. 

OPTCD specifies the subparameters that govern the request defined by the 
request parameter list identified by SKP and UPD. 
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GET Macro (Retrieve a Record) 



The format of the GET macro is: 



\labe/\ GET RPf = address 



where: 



label 

is I to 8 characters that provide a symbolic address for the GET macro. 
RPL^ address 

specifics the address of the request parameter list that defines this GET 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-type address constant. 



Example I: Keyed-Sequential Retrieval (Forward) 



In this example, a GET macro is used to sequentially retrieve records by key. 
Retrieval is in a forward direction. Fixed-length, 100-byte records are moved to a 
work area. Processing^is synchronaus. 



INPUT ACB 



RETRVE RPL 



MACRF=(KEY, 
SEQ, IN) 



ACB=INPUT, 

AREA=IN, 

AREALEN=100, 

OPTGD=(KEY,SEQ, 

SYN,NUP,MVE) 



All MACRF and OPTCD 
subparameters specified are 
defaults and could have 
been omitted. 



LOOP GET RPL=RETRVE 

LTR 15,15 
BNZ ERROR 



This GET or identical GETs can 
be issued, with no change in 
the request parameter list, to 
retrieve subsequent records in 
key sequence. 



B 



ERROR 



LOOP 



Request was not accepted, or 
failed. 



IN 



DS CLIOO 



IN contains a data record after 
GET is completed. 



The records are retrieved in key sequence in a forward direction. No search 
argument has to be specified; VSAM is positioned at the first record in key 
sequence when the data set is opened, and the next record is retrieved 
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automatically as each GET is issued. The branch to ERROR could also be 
taken if the end of the data set is reached. 



Example 2: Keyed-Sequential Retrieval (Backward) 



This example is the same as the previous one, except that a POINT macro 
instruction is issued to the last record in the data set and the records are retrieved 
in a backward direction. 



INPUT ACB DDNAME=INPUT, 
EXLST=EXLST1 

RETRVE RPL ACB=INPUT, 
AREA=IN, 
AREALEN=100, 
OPTCD=(KEY,SEQ, 
LRD,BWD) 

EXLSTl EXLST EODAD=EOD 

POINT RPL^RETRVE 

LTR 15,15 

BNZ ERROR 

LOOP GET RPL=RETRVE 

LTR 15,15 

BNZ ERROR 



Define RPL for last record 
positioning and backward 
processing. 



Define end of data. 

Positioi) to last record (no 
argument is required). 



Get previous record. 



EOD 
ERROR 



B 

EQU 



LOOP 
* 



Come here for end of data. 
Request failed. 



IN DS 



CLIOO 



Area for retrieved record. 



Example 3: Skip-Sequential Retrieval 



In this example, a GET macro is used to retrieve variable-length records 
synchronously. Records are to be processed in the 1/0 buffer. The search 
argument is full key, compared grcatcr-than-or-equal; key length is eight bytes. 

The records are retrieved in key sequence, but some records arc skipped. 
Skip-sequential retrieval is similar to keyed-direct retrieval, except that you must 
retrieve records in ascending sequence (with skips) rather than in a random 
sequence. 



GENCB BLK=ACB, 

DDNAME=INPUT, 

MAGRF=(KEY. 

SKP,IN) 



LTR 15,15 



VSAN gets an area in 
virtual storage to generate 
the access method control 
block and returns the 
address in register 1. 
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BNZ 
LR 



CHECKO 
2,1 



GENCB BLK=RPL, 
ACB=(2), 
AREA=RCDADDR, 
AREALEN=4, 
ARG=SRCHKEY, 
OPTCD=(KEY,SKP, 
SYN,NUP,KGE, 
FKS,LOC) 



LTR 
BNZ 
LR 



15,15 

CHECKO 

3,1 



LOOP MVC SRCHKEY, source 

GET RPL=(3) 

LTR 15,15 

BNZ ERROR 

SHOWCB AREA=RCDLEN, 

FIELDS=RECLEN, 

LENGTH=4, 

RPL=(3) 

LTR 15,15 

BNZ CHECKO 



Address of the request 
parameter list. 



Search argument for 
retrieval, moved in from 
a table or a transaction 
record. 



Display the length of the 
record. 



ERROR 



CHECKO 



LOOP 



Request was not accepted, 
or failed. 

Generation or display 
failed. 



RCDAODR DS 

SRCHKEY DS 
RCDLEN DS 



CL8 
F 



Work area into which VSAM puts 
the address of a data record 
within the I/O buffer 
(OPTCD=LOC). 

Search argument for retrieval. 

For displaying variable record 
lengths. 



The macros and instructions are as follows: 
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The first GENCB generates an access method control block, which specifies 
keyed, skip-sequential, and input processing. The address of the access 
method control block is stored in register 2. 

The second GENCB generates a request parameter list. The address of the 
request parameter list is stored in re^ster 3. 

MVC moves the search argument into SRCIIKEY, the area defined for the 
search argument. 

GET specifies that the record pointed at by the request parameter list whose 
address is in re^ster 3 is to be retrieved. Records are retrieved by a 
skip-sequential search through the sequence set of the index. 



Example 4: Addrcsscd-Scqucntial Retrieval 



In this example, one GET macro is used to retrieve multiple fixed-length, 20-byte 
records. The records are moved to a work area (only option). 



BLOCK ACB 



DDNAME=INPUT, 

MACRF=(ADR,SEQ, 

IN) 



GENCB 



LTR 

BNZ 

LA 

LR 

LR 



SR 
DR 

LR 

LR 
LA 



BLK=RPL, 

COPIES=10, 

ACB=BLOCK, 

OPTCD=(ADR,SEQ, 

SYN,NUP,MVE) 

15,15 

CHECKO 

3,10 

2,1 

1,0 



0,0 
0,3 

3,1 
4,2 

5,RECAREA 



Number of lists (10). 

Address of the first list. 

Length of all of the lists. 
Registers 0 and 1 contain 
length and address of the 
generated control blocks 
when VSAM returns control 
after GENCB. 

Prepare for following division. 

Divide number of lists into 
length of all the lists. 

Save the resulting length of a 
single list for an offset. 

Save address of the first 
list. 

Address of the first work 
area. 

Do the following 6 
instructions 10 times to set 
up all the request parameters 
lists. The 10th time, register 
4 must be set to 0 to indicate 
the last request parameter 
list in the chain. 
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AR 

MODCB 

LTR 
BNZ 
AR 
LA 

• 

• 

LOOP GET 
LTR 
BNZ 

B 

cmcm . . . 

ERROR 



RECAREA OS CL200 



4,3 

RPL=(2). 
NXTRPL=(4), 
AREA=(5), 
AREALEN»20 

15,15 

CHECKO 

2,3 

5,20(5) 



RPL=(2) 

15,15 

ERROR 

LOOP 



Address the next list. 

In each request parameter list, 
indicate the address of the 
next list and the address and 
length of the work area. 



Address the next list. 

Address the next work area. 
Restore register 2 to address 
the first list before continuing 
to orocess. 



Process the 10 records that 
have been retrieved by the 
GET. 



Display the feedback field 
(FIELDS=FDBK) of each request 
parameter list to find out 
which one had an error. 

Space for a work area for each 
of the 10 request parameter 
lists. 



llie GHNCB macro generates 10 request parameter lists; the lists are 
subsequently chained together by using the MODCB macro to modify the 
NXTRPL parameter in each copy. Because SEQ is specified in each request 
parameter list and no previous request has been issued against the access method 
control block since it was opened, retrieval beg^ at the beginning of the data set. 
Each time the GET macro is executed, VSAM is positioned at the next record in 
RBA sequence. VSAM moves each record into the work area provided for the 
request parameter list that identifies the record. 

If an error occurred for one of the request parameter lists in the chain and you 
have supplied error-analysis routines, VSAM takes a LERAD or SYNAD exit 
before returning to your program. Register 15 is set to indicate the status of the 
request. A code of 0 indicates that no error was associated with any of the 
request parameter lists. Any other code indicates that an error occurred for one 
of the request parameter lists. You should issue a SFIOWCB macro for each 
request parameter list in the chain to find out which had an error. VSAM 
doesn't process any of the request parameter lists except the one with an error. 
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Example 5: Sequential Retrieval for a Relative Record Data Set 



In this example, a GET macro is used to sequentially retrieve records by relative 
lecord number. Fixed-length, 100-byte records are moved to a work area. 
Processing is synchronous. 

INPUT ACB MACRF=(KEY,S£Q, All HACRF and OPTCD 

IN) - subparameters specified are 

defaults and could have been 
omitted. 



RETRVE RPL ACB=INPUT, 
AREA^IN, 
AR£ALEN=100, 
ARG=RCDNO, 
OPTCD=(KEY,SEQ, 
SNy,NUP,MVE) 



LOOP GET RPL^RETRVE 



LTR 15,15 
BNZ ERROR 



This GET or identical GETs 
can be issued, with no change 
in the RPL, to retrieve 
subsequent records in relative 
recora number sequence. 



B LOOP 

ERROR . . . Request was not accepted or 

it failed. 



IN 



DS CLIOO 



RCDNO DS CL4 



IN contains a data record 
afZer GET is -compJ^tad. 

VSAM returns relative record 
number of retrieved record in 
this field. 



The records arc retrieved in relative record number sequence. Empty records are 
bypassed for sequential retrieval. A 4-byte search argument must be specified. 
The relative record number of each record retrieved is stored in the search 
argument. VSAM is positioned at the first relative record when the data set is 
opened, and the next nonempty record is retrieved automatically as each GET is 
issued. The branch to ERROR would also be taken if the end of the data set is 
reached. 
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Example 6: Keyed-Direct Retrieval 



In this example, a GET macro is used to retrieve fixed-length, 100-byte records 
directly by key. Hie key length is 15 bytes; the search argument is a 5-byte 
generic key, compared equal. The control blocks are generated at assembly. 



INPUT ACB 



RETRVE RPL 



MACRF=(KEY, 
DIR. IN) 

ACB=INPUT, 

AREA=IN, 

AREALEN=4, 

OPTCD=(KEY, 

DIR,SYN,NUP, 

KEQ,GEN,LOC), 

ARG=KEYAR£A, 

KEYLEN=5 



You specify all parameters for 
the request in the RPL macro. 



LOOP MVC KEYAREA, SOURCE 



GET RPL=RETRVE 



LTK 15,15 
BNZ ERROR 



Search argument for retrieval, 
moved in from a table or a 
transaction record. 

This GET or identical GETs can 
be issued with no change in the 
RPL: Specify each new search 
argument in the field KEYAREA. 



Process the record. 



ERROR 



LOOP 



Request was not accepted, or 
failed. 



IN 



DS CL4 



KEYAREA DS CL5 



VSAM puts here the address of 
the record within the I/O 
buffer. 

You specify the search argument 
here. 



The generic key specifics a class of records. For example, if you search on the 
first third of employee number, VSAM positions at and retrieves the first of 
presumably several records that start with the specified characters. To retrieve all 
the records in that class, either switch to sequential access or to a full-key search 
with a greater-than-or-equal comparison. 
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Example 7: Addrcsscd-Direct Retrieval 



In this example, a GET macro is used to retrieve fixed-length 20-byte records. 
The records are to be moved to a work area. 

BLOCK ACB DDNAME=INPUT, Access method control 
MACRF=(ADR, DIR, block generated at 
IN) assembly. 



6ENCB BLK=RPL, 
C0PIES=1, 
ACB=BLOCK, 
OPTCD=(ADR, DIR, 
SYN, NUP, MVE) 

LTR 15,15 

BNZ CHECKO 

LR 2, 1 



ARG=SRCHADR, AREA=IN, 
AREALEN=20 

Request parameter list 
generated at execution. 



Address of the list. 



LOOP 



MVC 

GET 
LTR 
BNZ 



SRCHADR, 

RPL=(2) 
15, 15 
ERROR 



Search argument for 
retrieval; calculated or 
moved in from a table or 
a transaction record. 



Process the record. 



CHECKO 
ERROR 



LOOP 



Generation failed. 

Request was not accepted, 
or failed. 



IN 



DS 



CL20 



VSAM puts a record here 
for each GET request. 



SRCHADR DS 



CL4 



You specify the RBA 
search argument here for 
each request. 



The RBA provided for a search argument must match the RBA of a record. 
Keyed insertion and deletion of records in a key-sequenced data set will probably 
cause the RBAs of some records to change. Therefore, if you process a 
key-sequenced data set by addressed-direct access (or by addressed-sequential 
access using POINT), you need to keep track of changes. You can use the 
JRNAD exit for this purpose. See "EXLST Macro (Generate an Exit List at 
Assembly Time)" on page 66. 
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Example 8: Switch from Direct to Sequential Retrieval 



In this example, GET macros are used to retrieve fixed-length, 100-byte records. 
The retrieval is via an alternate kidex path defined with the nonunique key 
option. Every time a nonunique key is retrieved, the program switches to 
sequential processing to retrieve the other records with the same key. The 
control blocks were generated at assembly, but the MODCB macro is used to 
modify the request piirameter list to permit switching from keyed-direct to 
keyed-sequential retrieval. For the direct request preceding sequential requests, 
the search argument is an 8-byte, generic key, compared equal. Positioning is 
requested for direct requests. 



INPUT 



ACB 



RETRVE RPL 



MACRF=(KEY,DIR, 
SEQ,IN) 



ACB=INPUT, 

AREA=IN, 

AREALEN=100, 

OPTCD=(KEY,DIR, 

SYN,NSP,KEQ, 

GEN,.MVE), 

ARG=KEYAREA, 

KEYLEN=C 



Both direct and 
sequential access 
specified. 

NSP specifies that VSAM 
is to remember its 
position. 



LOOPl GET 
LTR 
BNZ 



KSYAREA, source 

RPL=RETRVE 

15,15 

ERROR 



Search argument for 
direct retrieval; moved 
in from a table or a 
transaction record. 



SEQ 



SHOWCB RPL=RETRVE, 

AREA=FDBAREA, 
FIELDS=FDBK 



LTR 
BNZ 
CLI 

BE 



15,15 
ERROR 
ERRCD,8 

SEQ 

LOOP 



MODCB RPL=RETRVE, 
OPTCD=SEQ 



LTR 15,15 
BNZ CHECKO 



Extract feedback 
information. 



Does a duplicate key 
follow? 

Yes; retrieve duplicates 
sequentially. 

No; retrieve next record 
in direct mode. 

Alter request parameter 
list for sequential 
access . 
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SEQGET 


GET 


RPL=RETRVE 


Do sequential retrieval. 




LTR 


15,15 


Test for error. 




BNZ 

• 


ERROR 






• 

SHOWCB 


RPLfRETRVE, 

AREA=FDBAREA, 

FIELDS^'FDBK 


Extract feedback 
information. 




LTR 


15,15 






BNZ 


ERROR 






CLI 


ERRCD, 8 


Does a duplicate key 
follow? 




BE 


SEQGET 


Yes ; retrieve 
sequentially. 


DIR 


HODCB 

LTR 
BNZ 


RPL=RETRVE, 
OPTCD=DIR 

15,15 

CHECKO 


Alter request parameter 
list for direct access. 




B 


LOOP 


Prepare new search 
argument . 


ERROR 






Request was not accepted 
or failed. 


cmcm 


• 




ifodi^ication failed. 


IN 


DS 


CLIOO 


VSAM puts retrieved 
records here . 


KEYAREA 


DS 


CL8 


Specify the generic key 
for a direct request 
here. 


FDBAREA 


DS 


OF 


Feedback area for SHOWCB 




Do 


10 


Reserved. 


TYPECD 


DS 


IC 


Error type code. 


CMPCD 


DS 


IC 


Component code. 


ERRCD 


DS 


IC 


Reason code. 



Positioning is associated with a request parameter list; the MODCB macro is 
used to modify a single request parameter list that alternately defines requests for 
both types of access rather than use a different request parameter list for each 
type. 



With direct retrieval, VSAM doesn't remember its position for subsequent 
sequential retrieval unless you explicitly request it (OPTCD = NSP or UPD). 
After a direct GET for update, VSAM is positioned for a subsequent PUT, 
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ERASE, or sequential GET. If you modify OPTCD= (DIR.NUP) to 
OPTCD=SEQ, you must issue POINT to get VSAM positioned for sequential 
retrieval, as NUP indicates that no positioning is desired with a direct GET. 

If you have chained many request parameter lists together, one position is 
remembered for the whole chain. For example, if you issue a GET that gives the 
address of the first request parameter list in the chain, the position of VSAM 
when the GET request is complete is at the record following the record defmed 
by the last request parameter list in the chain. Therefore, modifying 
OFrCD = (DIR,NSP) in each request parameter list in a chain to 
OPTCD^SEQ implies continuing with sequential access relative to the last of 
the direct request parameter Usts. 
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GETIX Macro (Retrieve an Index Record) 

The format of the GETIX macro is: 



\label[ 



GETIX 



RPL'^ address 



where: 
label 

is 1 to 8 characters that provide a symbolic address for the GETIX macro. 
RPL'' address 

specifies the address of the request parameter list that defmcs this GETIX 
request. You may specify the address in re^ster notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-type address constant. 

The following RPL parameters and subparameters are required for GETIX: 

OPTCD = (CNV 
,DIR 

,{NUP|UPI)|NSP) 
,{LOC|MVE}) 

GETIX can be issued either for update or not for update; 
OPTCD= NSP is interpreted as OPTCD= NUP. 

With OPTCD= MVE, AREALEN must be at least index control 
interval size. 

ARG = address 

The search argument for GETIX is the RBA of a control interval. 

To process the index of a key-sequenced data set with GETIX, you must open 

the cluster with: 

ACB MACRF=(CNV, . . . ) 



Chapter 2. VSAM Macro Formats and Examples 97 



MNTACQ 

MNTACQ Macro (Mount Acquire) 

The fomiat of the MNTACQ macro is: 



\labeH MNTACQ RFL'' address 



RPL = address 

specifies the address of the RPL that identifies your opened VSAM data set 
and your arguments. The following RPL parameters have meaning for 
MNTACQ: 

ACB'^ address 

identifies your VSAM data set. 

ARG"^ address 

identifies your arguments, address points to a parameter list, aligned 
on a fullword boundary as follows: 



Offset 


Length 


Contents 


0 


4 


Feedback area: address of an 
ECB WAIT list 


4 


6 


VOLSER, target volume 


10 


1 


Reserved 


11 


1 


Argument entry count (N) 
(N = 1 to 255) 


12 


4N 


Argument entries 


12+4(N-1) 


4 RBA for which an ACQUIRE is 
requested 



The maximum number of arguments is 255. 

For the specified list, MNTACQ will acquire (stage) the data cylinders 
corresponding to each RBA for the one given volume, llie volume 
will be mounted if necessary. 

OPTCD=((ADR|KEY} 
,{ASY|SYN) 
,{KEQ|KGE) 
,FKS) 

ADR is valid for entry-sequenced data set, error for key-sequenced 
data set or relative record data set. 
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KEY is valid for key-sequenced data sei and relative record data set, 
error for entry-scquenced data set. 

If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of ECBs (in 
standard WAIT list format) which you may use in place of the 
RPLECB field. 

GEN is not supported; if specified, it wiU ^ve an error indication. 

All other OPTCD parameters are not applicable, and, if specified, are 
ignored with no error indication. 

Because your request may result in the staging of numerous cylinders, a single 
ECB is not sufilcient for an asynchronous MNl'ACQ request. TTie RPLECB 
field is inoperative for the MNTACQ interface. Upon return from an 
asynchronous MNTACQ, the feedback area of the MNTACQ parameter list will 
contain the address of a standard ECB WAIT list. You must then use this list in 
conjunction with the WAIT macro or you may use the list in conjunction with 
the EVEN! S macro of MVS. An asynchronous request must conclude with 
either CHECK, ENDREQ, or CLOSE. 

At the conclusion of this macro, the RPL is disconnected in a manner similar to 
that of a direct VSAM request. Any positioning in effect prior to execution of 
this macro will be lost. You may have to rcnnsition. Chained RPLs are not 
supported by MNTACQ. 
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MODCB Macro (Modify an Access Method Control Block) 

The format of the MODCB macro used to modify an access method control 
block is: 



[labels 


MODCB 


ACS'' address 






(BSTRNO = number] 






lBVV>iD''number\ 






IBUVNl-' nunU)er\ 






IBVVSP = number] 






|,CATALOC « YESjNOI 






(,CRA»SCRA|UCRA| 






j,DDNAME = ddname\ 






l¥XlJSl^address\ 






|,MACRF - (|ADR||,CNV|(,KEY| 






I.CFTCINFXI 






|,1)DN|DSN| 






|,DFR|NDFI 






I,DIR||,SEQ|I,SKP| 






(,ICI|NCI| 






I,IN 11,01711 






|,MS|SIS| 






(,NRM|AIXI 






UNRSlRSIl 






|,NSR|LSR|GSR) 






(,NUB|UBF|)I 






|,MAREA = address] 






IMLEN^ number] 






I? XSSWO = address] 






|,R.MODF3i = fAIXIBUFFICBINONEJI 






[,SIIRPOOL = /zM/n6ert 






ISIVCSO^ number] 



Note: The RMODE31 parameter replaces the AM0DE31 subparameter shown 
in previous releases. 

The parameters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the MODCB macro. 
ACB = address 

specifies the address of the access method control block to be modified. 
The data set identified by the access method control block must not be 
opened. A request to modify the access method control block of an open 
data set will fail. 
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MODCB^ACB 



Note: The remaining parameters represent parameters of the ACB macro that 
can be modified. The value specified replaces the value, if any, presently in the 
access method control block. There are no defaults. For an explanation of these 
parameters, see "ACB Macro (Generate an Access Method Control Block at 
Assembly Time)*' on page 34. 

If MODCB is used to modify a MACRF subparameter, other subparameters are 
unaffected, except when they are mutually exclusive. For example, if you specify 
MACRF = ADR in the MODCB and MACRF = KEY is already indicated in the 
control block, both ADR and KEY wiU now be indicated. But, if you specify 
MACRF = UBF in the MODCB and NUB is indicated, only UBF will now be 
indicated. 

The RM0DE31 parameter tells the VSAM OPEN routines where to obtain 
storage for the control blocks and I/O buffers. Therefore, the only time the 
values specified by the RM0DE31 parameter have any effect on VSAM is on the 
setting just before an OPEN is issued. At other times, chan^g these values has 
no effect on the residency of the control blocks and I/O buffers. 

If MODCB RPL is used to change the address of an ACB, you must first issue 
an ENDREQ macro. 

Example: MODCB Macro (Modify an Access Method Control Block) 

In this example, a MODCB macro is used to modify the name of the exit list in 
an access method control block. 

MODCB ACB=BLOCK, BLOCK was generated at 

£XLST=E6R£SS assembly. 



Chapter 2. VSAM Macro Formats and Examples 101 



MODCB-EXLST 

MODCB Macro (Modify an Exit List) 



The fonnat of the MODCB macro used to modify an exit list is: 





MODCB 


EXLSJ» address 






|,EODAD - {[address^MMXm 






MRNAD » i\address]l\\^\m)\ 






|,L£RAD « {{address\i,A\f<\m)\ 






I^YNAD - {\address^,A\MM)\ 



The subparamcters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-typc address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

Note: See Data Facility Product: Customization for the factors that determine 
the addressing mode and the parameter list residency mode set when the exit 
routine gets control. 

iabei 

is 1 to 8 characters that provide a symbolic address for the MODCB macro. 
hXlSV-^addrvss 

specifies the address of the exit list to be modified. You can modify an exit 
list at any time— that is, before or after opening the data set(s) for which the 
list indicates exit routines. You cannot, however, add an entry to the exit 
list if it will change the exit list's length; the exit list must already be large 
enough to contain the new exit address. The order in which addresses arc 
stored in the EXLST control block is: l-QDAD, SYNAD, LERAD, 
JRNAD, and UPAD. For example, if you generate an exit list with only 
the LERAD exit, you can add entries for EODAD and SYNAD later; you 
cannot add the JRNAD exit address, because doing so would increase the 
size of the EXLST control block. The MODCB macro does not support 
the UPAD user exit. 

Note: If the JRNAD exit is changed for an OPEN ACB, then the ACB 
must be closed and reopened in order to use the modified JRNAD exit. 

For more information about user exit routines sec Data Facility Product: 
Customization, 

The remaining parameters represent parameters of the EXLST macro that can be 
modified or added to an exit list. For an explanation of these parameters, see 
"EXLST Macro (Generate an Exit List at Assembly Time)" on p^ge 66. 
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MODCB-EXLST 



Example: MODCB Macro (Modify an Exit List) 

In this example, a MODCB macro is used to activate an exit in an exit list. 

MODCB EXLST=(*. Indirect notation is used 

EXLSTADR), to specify the address of 

EODAD=(EOD,L,A) the exit list, which was 
generated at execution. 



EOD DC C* ENDUP* 

EXLSTADR DS F When the exit list was 

generated, its address was 



saved here. 



The MODCB macro's parameters arc: 



• EXLST specifics that the address of the exit list to be modified is located at 
EXLSTADR. 



EODAD specifics that the entry for the end-of-data routine is to be marKed 
active in the exit list whose address resides at EXLSTADR. The name of the 
end-of-data routine, ENDUP, is located at EOD. 
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M ODCB Macro (Modify a Request Parameter List) 



The fonnat of a MODCB macro used to modify a request parameter list is: 





MODCB 


RPL'' address 






lACB' address\ 






lAREA addressl 






lAREALEN'- number] 






{yARG ^addressl 






IECB = address] 






IKEYhES ^numbef\ 






(,MSGAREA address] 






IMSGLEN = number] 






|,NXTRPL = at/</rejj| 






IjOPTCD (IADR|CNV|KEY| 






|,DIRiSEQ|SKP| 






|,ARD|LRD| 






|,FWD|BVVDI 






I,ASY|SYN| 






|,NSP|NUP|LPDf 






|,KKQiKGE| 






|,FKS|GEN| 






|,LOCfMVEI)| 






f,RECi:EN = number] 






ITRASSny-' number] 



The parameters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-type address 
I constants, and as indirect S-type address constants. Appendix C, "Operand 

I Notation" on page 181, further defines these operand expressions. 

label 

is i to 8 characters that provide a symbolic address for the MODCB macro 
RPL'' address 

specifies the address of the request parameter list to be modified. You may 
not modify an active request parameter list; that is, one that defines a 
request that has been issued but not completed. To modify such a request 
parameter list, you must first issue a CHECK or an ENDREQ macro. 

Note: The remaining parameters represent parameters of the RPL macro that 
can be modified. The value specified replaces the value, if any, presently in the 
request parameter list. There are no defaults. For an explanation of these 
parameters, see "GENCB Macro (Generate a Request Parameter List at 
Execution Time)" on page 80. 

If MODCB is used to modify an OPTCD subparameter within a group of 
subparameters, the current subparameter for that group is changed, because only 
one subparameter in a group is effective at a time. Only the OPTCD 
subparameter specified is changed; all other OPTCD subparameters remain 
unchanged. 
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MODCB-RPL 



Example: MODCB Macro (Modify a Request Parameter List) 

In this example, a MODCB macro is used to modify the record length field in a 
request parameter list. 

Note: This example also shows the one exception to GENCB, MODCB, 
SHOWCB, and TESTCB building a parameter list and passing it to the control 
block manipulation module in register 1. In this example, the RPL address (in 
register 2) would be loaded into rc^ster 1 and the RECLEN value (in re^ster 3) 
would be loaded into rc^stcr 0. These registers would be passed to the control 
block manipulation macro. This will occur if the LIST, EXECUTE, or 
GENERATE form of the MODCB macro is not used and the only parameter 
specified, besides RPL, is RECLEN. 

L 3, length Load the new record length. 

MODCB RPL=(2), Register 2 contains the address 

of the request parameter list. 

RECLEN=(3) Register 3 contains the record 
length. 



llie MODCB macro's parameters are: 

• RPL specifies that register 2 contains the address of the request parameter list 
to be modified. 

• RECLEN specifies that the record length field is to be modified. The 
contents of re^ster 3 will replace any current value in the RECLEN field. 
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MRKBFR 

MRKBFR Macro (Mark Buffer) 

The format of the MRKBFR macro is: 



MRKBFR 



MARK - {DINVALIDIXINVALIDIOUTIRLS) 
fRPL" address 



MARK » {OINVALIDlXCWALIDiOUTIRLS} 

specifies whether to mark for output or to release from exclusive control or 
shared status the buffer identified in the RPL. To do both, issue 
MRKBFR twice, once with MARK = OUT, again with MARK = RLS. 

DINVALIDIXINVAIJD 

specifies whether to mark the data component or index component 
buffers invalid. The buffers to be invalidated arc identified as those 
which contain records, whose RBA values are within the RBA range 
pointed to by the RPL ARG address. DINVALID specifies that the 
data component buffers are to be marked invalid; XINVALID 
specifies that the index component buffers are to be marked invalid. 

OUT 

indicates that the buffer is to be marked for output. The buffer is 
kept under exclusive control or in shared status. 

RLS 

indicates that the buffer is to be released from exclusive control or 
shared status. 

RPL-' address 

specifies the address of the request parameter list that defines the 
MRKBFR request. Use the RPL used by SCIIBFR or GET to locate the 
buffer being marked or released. These RPL parameters have meaning for 
MRKBFR: 

ACB^ address 



ARG = address 

I The address of the 8-byte field that contains the beginning and ending 

I RBAs of the range to be searched on. 

ECB- address 



TRA^SID^ number 

All other RPL parameters are ignored. RPLs are assumed not to be 
chained. OPTCD'^ LOG is assumed. 

If the ACB to which the RPL is related has MACRF = GSR, the 
program that issues MRKBFR must be in supervisor state with 
protection key 0 to 7. 
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OPEN 

I OPEN Macro (Connect Program and Data) 



The fonnat of the OPEN macro is: 



[labeli 


OPEN 


(addressj\(options)\,...) 






|,M01)E = {24131)1 



iabel 

is 1 to 8 characters that provide a symbolic address for the OPEN macro. 
address 

I specifies the address of the ACB or DCB for the data set(s) to be opened. 

You may specify the address in register notation (using a register from 2 
through 12, in parentheses) or specify it with an expression that generates a 
valid relocatable A-type address constant. If you use re^ster notation to 
open only one data set, you must enclose the expression identifying the 
register in two sets of parentheses: for example, OPEN ((2)). 

options 

are options parameters for use only in opening non-VSAM data sets. If 
any options are specified with the address of an access method control 
block, VSAM ignores them. 

I MODE - 

I specifies the format of the OPEN parameter list that is to be generated. 

J 24 

I spHJcifies that a standard form (24-bit) parameter list address is to be 

I generated. The parameter list must reside below 16 megabytes and 

I point to an ACB residing below 16 megabytes. This is the default 

I parameter. 

I 31 

I specifies that a long form (31 -bit) parameter list address is to be 

I generated. TTiis parameter value must be coded if the parameter list 

I or the VSAM/VTAM ACB resides above 16 megabytes. 

I Note: If the VSAM control blocks and buffers are to reside above 16 megabytes, 

I the RMODE31 parameter must be specified in the ACB before the OPEN is 

I issued. 

Because the OPEN parameters are positional, include a comma for options (even 
if you don't specify options) before a subsequent parameter. 
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OPEN 



Example 1: OPEN Macro used to open two data sets. 



In this example, the access method control block for one data set was generated 
at execution; the other was generated at assembly. 



6ENCB BLK=ACB, 

DDNAME^^DATA 



An access method control block. 



LTR 
BNZ 

OPEN 



15,15 
ERROR 
2,1 

(BLOCK,, (2)) 



BLOCK ACB 



Address of the control block. 

A label is used for the access 
method control block generated 
by ACB; register notation is used 
for the one generated by GENCB. 
The two commas indicate the 
omission of options. 

Another access method control 
block. 



Example 2: OPEN Macro with a parameter list above 16 megabytes. 



This example shows a program being opened with a parameter list that may 
reside above 16 megabytes. 



OPLSTA OPEN 
OPLSTB OPEN 



M0DE=31, 
MF=(E, OPLSTB) 

(ACB1,,ACB2), 

M0DE=31, 

MF=L 



Since MODE =31 is coded in the list form of the OPEN macro, VSAM ACBs 
and the OPEN parameter list may reside above 16 megabytes. 

Note: Consistency must be maintained while using the MODE operand in the 
MF = L and MF = E versions of the OPEN macro. If MODE = 3 1 is specified in 
the MF~ L version, then MODE — 31 must also be coded in the corresponding 
MF - E version of the macro. Unpredictable results may occur if this rule is not 
followed. 



MF«E and MF = L arc not required. OPEN (ACBl), M0DE=*31 is also valid. 



108 MVS/XA VSAM Administration: Macro Instruction Reference 



POINT 



POINT Macro (Position for Access) 

The format of the POINT macro is: 



\labeli POINT RFL'- address 



label 

is 1 to 8 characters that provide a symbolic address for the POINl' macro. 
RVL'^ address 

specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 



Example: Position with POINT 



In this example, the POINT macro is used to position at a record identified by a 
full key (5-b>'te) search argument, compared equal. 
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BLOCK ACB 
POSITION RPL 



DDNAME^IO 



Default MACRF subparameters 
sufficient. 



ACB=BLOCK, 
AREA^ORK, 
AR£ALEN~50» 
ARG=SRCHKEY, 
OPTCD=(KEY, SEQ, SYN,KEQ,FKS) 



AR6 parameter and KEQ and 
FKS OPTCO subparameters 
define the POI^f^ request. 



Search argument for 
positioning, moved in from 
a table or a transaction 
record. 



LOOP MVC SRCHKEY, source 
POINT RPL=POSITION 

LTR 15,15 
BNZ ERROR 
LOOPl GET RPIfPOSITION 
LTR 15,15 
BNZ ERROR 

Process the record. Decide whether to skip to another 
position (forward or backward). 



BE 
B 



LOOP 
LOOPl 



ERROR 
SRCHKEY DS 
WORK DS 



CL5 
CL50 



Yes; skip. 

No; continue in 
conseeirtive sequence. 

Request was not accepted, 
or failed. 

Search argument for 
positioning. 

VSAM puts a record here 
for each GET request. 
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PUT Macro (Store a Record) 



The format of the PUT macro is: 



PUT 



RPL = address 



label 

is 1 to 8 characters that provide a symbolic address for the PUT macro. 
RPL = address 

specifies the address of the request parameter list that defmes the request. 
You may specify the address in register notation (using a re^ster from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 

Note: If the PUT macro is being used to load records into an empty data set, 
the SI RNO value in the access method control block must be 1, and RPL 
OPTCD- DIR must not be specified. However, for an empty relative record 
data set, DIR is allowed. 



Example 1: Keyed-Sequential Insertion 



In this example, a PUT macro is used to perform keyed-sequential insertion. 
Variable-length records with a key length of 15 bytes are to be moved from a 
work area. Some records will be inserted between existing records; other records 
will be added at the end of the data set. 



BLOCK 
LIST 



ACB DDNAME^OUTPUT, 

MACRF=( KE Y , SEQ , OUT) 

RPL ACB=BLOCK, 

AREA=BUILDRCD, 
AREALEN=250, 
OPTDC=(KEY,SEQ, 
SYN,NUP,MVE) 



LOOP 



2, source 



MODCB RPL=LIST, 
RECLEN=(2) 



Put length of record to 
be inserted into 
register. 

Indicate record length 
in request parameter 
list. 



LTR 
BNZ 
PUT 
LTR 
BNZ 
B 



15,15 

CHECKO 

RPL=LIST 

15,15 

ERROR 

LOOP 



CHECKO 



Modification failed, 
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PUT 



ERROR . . . Request was not accepted^ 

or failed. 

BUILDRCO OS CL250 Work area for building 

records . 

The request parameter list, LIST, is associated with the access method control 
block, BLOCK. The length of each record to be inserted is put into register 2, 
which is subsequently used by MODCB to change the record length in the 
request parameter list. The record length is, therefore, correctly indicated in the 
request parameter list before the PUT macro is issued. The execution of the 
PUT macro causes VSAM to skip ahead (never back) to the next record. 



Example 2: Recording RBAs When Loading 



In this example, a PUT macro is used to record the RBAs of records as they are 
loaded into a key-sequenced data set. The RBAs are recorded in a table with 
20-byte entries (4 bytes for RBA, 15 bytes for associated key, and 1 byte of 
padding so the next entry bc|^s on a fullword boundary). 



LA 



3,RBATABLE 



Address of the begirming of 
the table. 



LOOP 



MODCB 

LTR 
BNZ 
PUT 
LTR 
BNZ 
SHOVCB 

LTR 
BNZ 
MVC 

LA 
B 



2, source 

RPL=LIST, 
REeLEN=(2> 

15,15 

CHECKO 

RPL=LIST 

15,15 

ERROR 

AREA=(3), 
FIELDS=RBA, 
LENGTH=4, 
RPL=LIST 

15,15 

CHECKO 

4(15,3), 
keyfield 

3,20(3) 

LOOP 



Put length of record to be 
inserted into register 2. 

Indicate record length in 
request paranreter lisrt. 



Each SHOWCB puts a record's 
RBA into the table. 



ERROR 



Put the record's key field 
in the table. 

Point to the next entry. 



Request was not accepted, 
or failed. 
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PUT 



CHECKO 



Modification or display 
failed. 



DSECT 



RBATABLE DS 
RBA DS 
KEY DS 
DS 



OF 
CL4 
CL15 
CLl 



Get enough virtual storage 
for as many table entries 
as there are records in 
the data set. 



Padding to keep each RBA 
entry on a fullword 
boundary: SHOWCB's display 
area must be on a fullword 
boundary. 

The need to process a key-sequenced data set by address should be unusual, but 
by recording the RBA of each record in a key-sequenced data set, you have 
search arguments for possible processing of the data set by addrcsscd-direct 
retrieval and by addrcsscd-scqucntial retrieval using the POINT macro. (You 
don't need to know RDAs to process a key-sequenced data set by simple 
addressed-sequential retrieval, since you go from the beginning without any 
skips.) 

You can display the RBA of a record after you issue a GET or a POINT, as well 
as after you issue a PUT. 

Example 3: I^oading a Relative Record Data Set (Skip-5>cqucntial and Direct Proccssiiig) 

In this example, a PUT macro is used to store twenty 100-byte records in slots 5, 
10, 15,..., 100 of the data set. MODCB is used to switch to direct processing, and 
a PUT is used to store records in slots 26 and 51 of the data set. 



OUTACB ACB 



MACRF=(SKP,OUT, 
DIR,KEY) 



GENCB BLK=RPL, 

ACB=OUTACB, 

AREA=WORK, 

AREALEN=100, 

ARG=RCDNO, 

OPTCD=(KEY,SKP) 



LTR 

BNZ 

LR 

LR 

LA 



15,15 

GENFAIL 

5,0 

6,1 

7.5 



ST 7,RCDN0 
LA 10,20 



Generate a request 
parameter list at 
execution time. 



Save length of RPL. 

Save address of RPL. 

Initialize increment 
value. 

Initialize argument to 
slot 5. 

Initialize loop counter. 
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LOOP 



Move new record into work. 



GENFAIL . . . 

PUTERR 

RETURN 
WORK 

RCDNO DS 



PUT 


RPL=(6) 


Store record. 


LTR 


15,15 




BNZ 
L 


PUTERR 
1, RCDNO 


Request was not accepted, 
or failed. 


AR 


1,7 




ST 


1, RCDNO 


Increment argument by 5. 


BCT 


10,L00P 




MODCB 
LTR 


RPL=(6), 
OPTCD=(DIR,KEY) 

15,15 


Switch to direct processing 
to store records in slots 
51 and 26. 


BNZ 


GENFAIL 




LA 


7,51 




ST 


7, RCDNO 


Initialize argument to slot 
51. 

Move new record into WOIUC. 


PUT 


RPL=(6) 


Store record in slot 51. 


LTR 


15,15 




BNZ 
LA 


PUTERR 
7,26 


Request was not accepted, 
or failed. 


ST 

• • • 


7, RCDNO 


Initialize argument to slot 
26. 

Move new record into WORK. 


PUT 


RPL=(6) 


Store record in slot 26. 


LTR 


15,15 




BNZ 


PUTERR 


Request was not accepted, 
or failed. 


B 

• • • 


RETURN 


Generation or modification 
failed. 

PUT request was not 

Aor* Ant* mr 4 1 pH 

Terminate program. 


DS 


CLIOO 


100 -byte work area that 
contains record to be 
stored by PUT macro. 


DS 


CL4 


4-byte relative record 



number. 
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PUT 



Both skip-sequential and direct processing can be used to create a relative record 
data set. The ACB is opened for output. The 4-byte search argument 
(RCDNO) indicates the slot number where the record is to be stored. 



Example 4: Keyed-Sequential Insertion (Relative Record Data Set) 



In this example, a PUT macro is used to insert twenty 100-byte records into 
empty slots of a previously loaded relative record data set. If the slot is empty 
when the PUT is issued, the record is stored and the slot number (returned in the 
argument field) is stored in a table. If the slot is not empty when the PU T is 
issued, a duplicate record error indication is rctumcd. When a duplicate record is 
indicated, the PUl' is reissued until the record is successfully stored in an empty 
slot in the data set. 



OUTACB ACB 



MACRF=(KEY,SEQ, 
OUT) 



GENCB BLK=RPL, 

ACB=OUTACB, 

AREA=WORK, 

AREALEN=100, 

ARG=RCDNO, 

OPTDC=(KEY,SEQ) 

LTR 15,15 

BNZ GENERR 

LR 6,1 

LA 4,RRNTABLE+80 

LA 3,RRNTABLE 



Generate a request parameter 
list. 



WRITERCD 



Save the address of the RPL. 

Initialize address of end of 
table. 

Initialize index to relative 
record number table. 

Move record into work area. 



PUT 
LTR 
BZ 
LA 

CLR 
BNE 



RPL=(6) 
15,15 
STRCDNO 
10,8 

10,15 
PUTERR 



Branch, if PUT is successful. 
Test for logical error. 



TESTCB RPL=(6),FDBK=8, Test for duplicate record. 
ERET=TESTERR 



BE WRITERCD 
B PUTERR 



Branch, if duplicate record, 
and try to store record in 
next slot. 
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PUT 



STROCNO 



MVC. 

LA 

CLR 
BE 

B 

6ENERR 
TESTERR . . . 
PUTERR 
RETURN . . 
RCDNO DS 
RRNTABLE DS 
WORK DS 



0(4,3)RCDNO 

3,4(3) 

3.4 

RETURN 
WRITERCD 



CIA 
20F 
CLIOO 



Store relative record 
number in RRNTABLE. 

Increment to next table 
entry. 



If table full, return to 
caller. 

Write next record. 

Error routine for GENCB 
macro. 

Error routine for TESTCB 
macro. 

Error routine for PUT 
macro. 

Return to caller or 
terminate program. 

4 -byte relative record 
number (argument) field. 

Relative record number 
talkie. 

100 -byte work area that 
contains record to be 
stored by PUT macro. 



Each record is stored in the next available slot in the data set. When a record is 
successfully stored, its relative record number is recorded in a table. 



Example 5: Skip-Sequential Insertion 



In this example, one PUT macro is used to insert multiple fixed-length, 100-byte 
records. Records are to be moved asynchronously from a work area. 



OUTPUT ACB MACRr=(KEY,SKP, 
OUT) 



GENCB BLK=RPL, 
C0PIES=5, 
ACB=OUTPUT, 
AREALEN=»100, 
OPTCD=(KEY,SKP, 
ASY,NUP,MVE), 
RECLEN^^^lOO 

LTR 15,15 

BNZ CHECKO 



Generate 5 request 
parameter lists at 
execution. 
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PUT 



Calculate length of each list and use register notation with 
the MODCB macro to complete each list. 

MODCB RPL=(2), 
AREA=(3), 
NXTRPL=(4) 

LTR 15,15 

BNZ CHECKO 

Increase the value in each register and repeat the MODCB 
until all five request parameter lists have been completed. 
The last time, register 4 must be set to 0. 



LOOP 



PUT RPL=(2) 

LTR 15,15 
BNZ NOTACCEP 



Restore address of first 
list in register 2. 
Build 5 records in WORK. 

Register 2 points to the 
first request parameter 
list in the chain. The 
five records in WORK are 
stored with this one 
PUT request. 



CHECK RPL=(2) 

LTR 15,15 

BNZ ERRO 

B LOOP 



CHECKO 

NOTACCEP 

ERROR 

WORK 



DS 



CL500 



Generation or modification 
failed. 



Display the feedback field 
in each request parameter 
list to find out which one 
had an error. 

Contains five 100 -byte work 
areas . 



You give no search argument for storage: VSAM knows the position of the key 
field in each record and extracts the key from it. Skip-sequential insertion differs 
from keyed-direct insertion in the sequence in which records may be inserted 
(ascending nonconsecutive sequence versus random sequence) and in 
performance. 

With skip-sequential insertion, if you insert two or more records into a control 
interval, VSAM doesn't write the contents of the buffer to direct-access storage 
until you have inserted all the records. With direct insertion, VSAM writes the 
contents of the buffer after you have inserted each record. 
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PUT 



Example 6: Keyed- Direct Insertion 



In this example, a PUT macro is used to move fixed-length, 100-bytc records 
from a work area. 



OUTPUT ACB 
DIRECT RPL 



MACRF=(KEy,DIR, 
OUT) 

ACB=OUTPUT, 

AREA^ORK, 

AREALEN»100, 

OPTCD=(KEY,DIR, 

ASY,NUP,MVE), 

RECLEN-lOO 



LOOP 



PUT 
LTR 
BNZ 



RPL=DIRECT 

15,15 

NOTACCEP 



B 

NOTACCEP ... 
ERROR 



CHECK RPL=DIRECT 
LTR 15,15 
ERROit 
LOOP 



Request was not accepted. 
Request failed. 



WORK DS CLIOO 

The macros are as follows: 



VTork area. 



• ACB specifies that the data set, OUTPUT, into which records are to be 
inserted) is opened for keyed-direct, output processing. 

• RPI. specifies that the record to be inserted into the OUTPUT data set 
resides in a lOO-bytc area, WORK. 

VSAM extracts the key from the key field of each record found at WORK. 
Using keyed-direct access is similar to using skip-sequential access. 



lis 
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Example 7: Addrcsscd-Scqucntial Addition 



In this example, a PUT macro is used to add variable-length records to a data 
set. The data set is assumed to be an entry-sequenced data set, because records 
cannot be inserted into or added to a key-sequenced data set with addressed 
access. 



BLOCK ACB MACRF=(ADR,SEQ, 
OUT) 

LIST RPL ACB=BLOCK, 

AREA=NEWRCD, 
AREALEN=100, 
OPTCD=(ADR,SEQ, 
SYN.MVE) 



LOOP 



3, source 



MODCB RPL=LIST, 
RECLEN=(3) 



LTR 
BNZ 
PUT 
LTR 
BNZ 
B 



CHECKO 
ERROR 



15,15 

CHECKO 

RPL=LIST 

15,15 

ERROR 

LOOP 



Build the record. 

Put the length of the 
record into register 3. 

Indicate length of new 
record. 



Modification failed. 



Request was not accepted, 
or failed. 



NEWRCD DS CLIOO Build record in this work 

area. 

Each record is stored in the next position after the last record in the data set. 
You do not have to specify an RBA or do any explicit positioning (with the 
POINT macro). Addressed addition of records is always identical to loading a 
data set: Wlien additional space is required, VSAM extends the data set. 

Ilie only difference between addrcssed-scquential and addresscd-dircct addition is 
when the buffers are written to external storage. The buffer is written to external 
storage only when it is full for sequential addition; it is written after each record 
for direct addition. You cannot use direct storage to load records into a data set 
for the first time; you must use sequential storage. 
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Example 8: Kcycd-Scqucntial Update 



In this example, GET and PUT macros are used to retrieve and update 
fixed-length, 50-byte records. Records are updated synchronously in a work area. 
This example requires the use of a work area because you cannot update a record 
in the I/O buffer. 

UPDATA ACB MACRF=(KEY,SEQ, 

OUT) 

LIST RPL ACB=UPDATA, UPD indicates the record may 

AR£A=WORK, be stored back (or deleted). 

AREALEN^SO, 
OPTCD=(KEY,SEQ, 
SYN,UPD,MVE) 



LOOP GET RPL=LIST 
LTR 15,15 
6NZ ERROR 



Decide whether to update the record. 



BE 



LOOP 



Do not update it; retrieve 
mother. 



Do update the record. 



PUT 
LTR 
BNZ 
B 



ERROR 



RPL=LIST 
15,15 
ERROR 
LOOP 



Store the record back. 



Request was not accepted, or 
failed. 



WORK DS CL50 VSAM puts the retrieved record 

here. 

A GET for update (OPTCD= UPD) must precede a PUT for update. Besides 
retrieving the record to be updated, GET positions VSAM at the record retrieved, 
in anticipation of the succeeding update (or deletion). It is not necessary for you 
to store back (or delete) the record that you retrieved for update. VSAM's 
position at the record previously retrieved allows you to issue another GET to 
retrieve the following record. You cannot then, however, store back the previous 
record: The position for update has been forgotten because of the following GET. 
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Example 9: Kcycd-Dircct Update 



In this example, GET and PUT macros are used to retrieve and update records. 
The MODCB macro is used to modify record length (RECLEN) in the request 
parameter list when an update causes the record length to change. The 
maximum record length is 120 bytes. The search argument is a full key (5 bytes), 
compared equal. 



INPUT ACB MACRF=(KEY,DIR, 
OUT) 

UPDTE RPL ACB=INPUT, 
AREA=IN, 
AREALEN=120, 
OPTDC=(KEY,DIR, 
SYN,UPD,KEQ, 
FKS,MVE), 
ARG=KEYAREA, 
KEyLEN=5 



UPDTE indicates the record 
may be stored back 
(or deleted) . 



Process input and get search argument into KEYAREA; proceed 
to retrieve a record. 



LOOP 



GET 
LTR 
BNZ 



RPL=UPDTE 

15,15 

ERROR 



SHOWCB RPL=UPDTE, 

AREA=RLNGTH, 

FIELDS=RECLEN, 

LENGTH=4 



LTR 
BNZ 



15,15 
CHECKO 



Display the length of the 
record. 



Update the record, 
length? 



STORE 



B£ 
L 



STORE 
5 , length 



Does the update change the record's 
No; length not changed. 



MODCB RPL=UPDTE, 
RECLEN=(5) 



LTR 


15,15 


BNZ 


CHECKO 


PUT 


RPL=UPDTE 


LTR 


15,15 


BNZ 


ERROR 


B 


LOOP 



Yes; load new length into 
register 5. 

Modify length indication 
in the request parameter 
list. 
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ERROR 



Request was not accepted^ or 
failed. 



CHECKO 



Display or modification 
failed. 



IN 



DS 



CL120 



Work area for retrieving, 
updating, and storing a 
record. 



KEYAREA DS 



CL5 



Search argument for 
retrieving a record. 



RLN6TH 



DS 



F 



Area for displaying the 
length of a retrieved record. 



You cannot update records in the I/O buffer. A direct GET for update positions 
VSAM at the record retrieved, in anticipation of storing back (or deleting) the 
record. This positioning also allows you to switch to sequential access to retrieve 
the next record. When PUT is issued after a DIRUPD GET request, PUT 
causes VSAM to release exclusive control. 

You do not have to store back a record that you retrieve for update, but, if you 
do not store it back before another retrieval, the current updates are lost. 
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Example 10: Addrcsscd-Scqucntial Update 



In this example, GET and PUT macros are used to retrieve and update records in 
an entry-sequenced data set. The records are variable in length, a maximum of 
200 bytes. The lengths of the records are not changed by update (the length of a 
record can never be changed by addressed access). 



ENTRY ACB MACRF=(ADR,SEQ,OUT) 



ADRUPD RPL 



ACB=ENTRY, 

AREA=WORK, 

AREALEN='200, 

OPTCD=(ADR,SEQ, 

SYN,UPD,MVE) 



UPDTE indicates update (or 
deletion) . 



LOOP GET RPL=ADRUPD 

LTR 15,15 

BNZ ERROR 

SHOWCB RPL=ADRUPD, 
AREA=RECLEN, 
FIELDS=RECLEN, 
LENGTH=4 

LTR 15,15 

BNZ CHECKO 



Find out how long the record 
is. 



PUT 
LTR 
BNZ 
B 



ERROR 



CHECKO 



RPL=ADRUPD 
15,13 
ERROR 
LOOP 



Request was not accepted, or 
failed. 

Display failed. 



WORK DS 
RLNGTH DS 



CL200 
F 



Record-processing work area. 

Display area for length of 
records . 



If you have inactive records in your cntry-scqucnced data set, you may reuse the 
space they occupy by retrieving the records for update and restoring a new record 
in their place. 

With a key-scquenccd data set, it is not possible to change the length of records 
by addressed update because the index is not used and VSAM could not split a 
control interval if required because of changuig record length. 

Addressed-direct update varies from sequential update in the specification of an 
RBA for a search argument. 
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Example 1 1: Marking Records Inactive 



In this example, GET and PUT macros are used to retrieve a record from an 
entry-scquenced data set and to mark it as inactive. {The record is marked as 
inactive by putting a hexadecimal 'FF' in the first byte of a record.) The inactive 
record will not be sequentially retrieved except for update. 

ENTRYSEQ ACB MACRF=(ADR,DIR, 

OUT) 

LIST RPL ACB=ENTRYSEQ, UPD indicates update; 

AREA=RECORD, storing the record back 

AREALEN=100, marked inactive. 

OPTCD=(ADR,DIR, 

SYN,UPD,MVE), 

ARG^RBAAREA 



LOOP GET RPL=LIST 
LTR 15,15 
BNZ ERROR 



Decide whether you still want the data in the record. 



BE LOOP 

MVI RECORD, X'FF' 

PUT RPL=LIST 

LTR 15,15 

BNZ ERROR 

B LOOP 



ERROR 



RECORD DS 



RBAAREA DS 



CLIOO 



Yes; retrieve the next 
record. 

No; flag the record 
inact ive. 

Storing the record with 
an inactive indicator is 
equivalent to deletion 
for an entry -sequenced 
data set. 



Request was not accepted, 
or failed. 

Work area for marking 
records . 

Search argument for 
retrieving the record. 



Records of an cntry-sequenccd data set can't be deleted. If a record loses its 
usefulness for your application, your program can mark it inactive by placing a 
unique flag in some conventional part of the record so that when your programs 
retrieve the record thereafter they can recognize and bypass it. You can use the 
space occupied by an inactive record by retrieving it for update and storing a new 
record in its place. 
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PUTIX Macro (Store an Index Record) 

The format of the PUTIX macro is: 



\label\ 



PUTIX 



RPL = address 



where: 
label 

is 1 to 8 characters that provide a symbolic address for the PUTIX macro. 
RVL^ address 

specifics the address of the request parameter list that defines this PUTIX 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-type address constant. 

The following RPL parameters and subparameters are required for PUTIX: 

OPrCD = (CNV 
,1)IR 
,UPD 
,MVE) 

OPTCD = LOC is not allowed. 

AREALEN 

must be at least index control interval size. 



The contents of a control interval must previously have been retrieved for update 
by way of GETIX. 

To process the index of a key-sequenccd data set with GETIX, you must open 
the cluster with: 

ACB MACRF=(CNV,...) 
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RPL Macro (Generate a Request Parameter List at Assembly Time) 



The format of the RPL macro is: 





RPL 


(ACB = address\ 






I.AM»VSAMI 






IARE\ = address] 






i,AREALEN = numberi 






|,ARG - address] 






IECB= address] 






(,KEYLEN = rtwwM 






|,MSGAREA = address] 






IMSGLFJS^ number] 






INX'IRVL-- address] 






|,OPTCD = (lADRiCNVIKEYl 






r.DlRISEOISKP| 






i,ARI)|LRD| 






IJ-VVDIBYVDI 






I,ASY|SYN| 






I,NSP|NtP|LPD| 






f,KEQ|KGEI 






(,FKS|GEN| 






LMVAITXIVVArrXI 






l,LOC|MVE|)| 






S^RECI^ET^^ number^ 






IIRASSID^ number] 



Values for RPL macro parameters can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-type address constants. 

label 

is 1 to 8 characters that provide a symbolic address for the request 
parameter list that is generated. You can use it in the request macros to 
give the address of the Ust. You can use it in the NXTRPL parameter of 
the RPL macro, when you are chaining request parameter lists, to indicate 
the next list. 

ACB = address 

specifies the address of the access method control block that identifies the 
data set to which access will be requested. If you used the ACB macro to 
generate the control block, you may specify the label of that macro for the 
address. If the ACB parameter is not coded, you must specify the address 
before issuing the request. 

AM = VSAM 

specifies that the access method using the control block is VSAM. 
AREA = address 

specifies the address of a work area to and from which VSAM moves a data 

record if you request it to do so (with the RPL parameter 

OPTCD= MVE). If your request is to process records in the I/O buffer 
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(OPTCD = LOC), VSAM puts into this work area the address of a data 
record within the I/O buffer. 

AREALEN = number 

specifies the length, in bytes, of the work area whose address is specified by 
the AREA parameter. Its minimum for DPTCD= MVE is the size of a 
data record (of the largest data record, for a data set with records of variable 
length). For OPTCD= lyOC, the area should be 4 bytes to contain the 
address of a data record within the I/O buffer. 

ARC « address 

specifies the address of a Held that contains the search argument for direct 
retrieval, skip-sequential retrieval, and positioning. For a relative record 
data set, the ARG field must be 4 bytes long. For direct or skip-sequential 
processing, this field contains your search argument, a relative record 
number. For sequential processing (OP'rCD = (KEY,SFQ)), the 4 bytes 
are required for VSAM to return the feedback RRN. For keyed access 
(OPTCD= KEY), the search argument is a full or generic key or relative 
record number; for addressed access (OP'rCD = ADR), it is an RBA. If 
you specify a generic key (OPTCD = GEN), you must also specify in the 
KEYLEN parameter how many of the bytes of the full key you are using 
for the generic key. ARG is also used with WR'l Bl-R and MRKBl R. Its 
usage with these macros is described in "Sharing Resources" in VSAM 
Administration Guide. 

ECB- address 

specifies the address of an event control block (ECB) that you may supply. 
VSAM indicates in the liCB whether a request is complete or not (using 
standard completion codes, wiiich are xlcscrihcd in Areas). You can 
use the ECB to determine that an asynchronous request is complete before 
issuing a CHECK macro. (If you issue a CHECK before a request is 
complete, you give up control and must wait for completion.) The ECB 
parameter is always optional. 

KEYLEN -/zwm^r 

specifies the length, in bytes, of the generic key (OPTCD = GEN) you are 
using for a search argument (^ven in the field addressed by the ARG 
parameter). This parameter is specified as a number from 1 through 255; it 
is required when the search argument is a generic key. For full-key 
searches, VSAM knows the key length, which is taken from the catalog 
definition of the data set when you open the data set. 

MSGARVA'- address 

specifies the address of an area that you may, optionally, supply for VSAM 
to send you a message in case of a physical error. The format of a physical 
error message is given in "Reason Code (Physical Errors)" on page 26. 

MSGLEN = number 

specifies the size, in bytes, of the message area indicated in the MSGAREA 
parameter. If MSGAREA is specified, MSGLEN is required. The 
minimum size of a message is 128 bytes; if you provide less than 128 bytes, 
no message is returned to your program. 
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NXTRPL^ address 

specifies the address of the next request parameter list in a chain. Uimt this 
parameter from the macro that generates the last list in the chain. When 
you issue a request that is defined by a chain of request parameter lists, 
incticate in the request macro the address of the first parameter list in the 
chain. 



OPTCD = (lADRICNVI KEYI 
I.DIRISEOISKPI 
URD ILRDI 
|,FVVl)|BWD| 
I.ASYI SYNI 
KNSPINUPiUPDi 
IKEQIKGEI 
|,FKS|(;EN| 
L NWAITX IWAITXl 
IXOCI MVEI) 

specifies the subparamctcrs that govcm the request defined by the request 
parameter Ust. Each group of subparameters has a default; subparameters 
are shown in Figure 13 with defaults underlined. Only one subparameter 
from each group can be specified. Some requests do not require an 
subptu-ameter from all of the groups to be specified. The groups that aren't 
required are ignored; thus, you can use the same request parameter list for a 
combination of requests (GET, PUT, POINT, for example) without 
zeroing out the inapplicable subparameters each time you go from one 
request to another. 



Option Moaning 

ADR Addressed access to a key-sequcnccd or an entry-sequcnced 

data set: RBAs are used as search arguments and sequential 
access is done by entry sequence. 

CNV Control interval access (this type of access is described in 

VSAM Administration Guide). 

KEY Keyed access to a key-sequenced or relative record data set: 

keys or relative record numbers are used as search arguments 
and sequential access is done by key or relative record number 
sequence. 

DIR Direct access to a key-sequenced, entiy-sequenced, or relative 

record data set. 

SEP Sequential access to a key-sequenced, entry-sequenced, or 

relative record data set. 

SKP Skip sequential access to a key-sequenced or a relative record 

data set: used with keyed access only. 



Figure 13 (Part 1 of 3>. OPTCD Options 
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Meaning 

User's argument detennines the record to be located, retrieved, 
or stored. 

LRD Last record in the data set is to be located (POINT) or 

retrieved (GET direct); requires OPTCD* BWD. 

Processing to proceed in a forward direction. 

Processing to proceed in a backward direction; for keyed 
(KEY) or addressed (ADR) sequential (SEQ) or direct (DIR) 
requests; valid for POINT, GET, PUT, and ERASE 
operations; establish positioning by a POINT with 
OPTCD = BWD or by a GET direct with 
OPTCD = (NSP,BWD). When OPTCD = BWD is specified, 
subparamcters KGE and GEN arc ignored; subparametcrs 
KEQ and FKS arc assumed. 

ASY Asynchronous access; VSAM returns to the processing 

program after scheduling a request so the program can do other 
processing while the request is being carried out. 

SV'N Synchronous access; VSAM returns to the processing program 

after completing a request. 

NSP With OPTCD = DIR only, VSAM is to remember its position 

(for subsequent sequential access); that is, the position is not to 
be forgotten unless an ENDREQ macro is issued. 

XUP A data record that is being retrieved will not be updated or 

deleted; ai^ocord that is being stOf<!d is a new fxxxsrd; VSAM 
doesn't remember its p>osition for direct requests into a work 
area. 

UPD A data record that is being retrieved may be updated or deleted; 

a record that is being stored or deleted was previously retrieved 
vkdth G?TCD= UPD; VSAM remembers its position for 
sequential and direct GET requests. When PUT is issued after 
a DIRUPD GET request, PUT causes VSAM to release 
exclusive control. 

KEQ For GET with OPTCD = (KEY.DIR) or (KEY,SKP) and for 

POINT with OPTCD = KEY, the key (full or generic) that you 
provide for a search argument must equal the key or relative 
record number of a record. For a relative record data set, KEQ 
is assumed except for POINT. 



Figure 13 (Part 2 of 3). OPI CI) Options 
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KGE For the same cases as KEQ, if the key (full or generic) that you 

provide for a search argument doesn't equal that of a record, 
the request applies to the record that has-the next higher key. 
For a relative record data set and POINT, KGE positions to 
the specified relative record number whether the slot is empty 
or not. If the relative record number is greater than the highest 
existing record, EOD is returned. A subsequent PUT will 
insert the record at this position. 



A full key is provided as a search argument. 

A generic key is provided as a search argument; give the length 
in the KEYLEN parameter. 

NWArrX Never take the user's UPAD exit. 



WATIX If OPTCD = SYN and the ACB's MACRF = LSR GSR and 

UPAD exit routing is specified, VSAM takes the UPAD exit at 
poults when VSAM would normally issue a WAIT. 

LOC l*or retrieval, VS"AM leaves the data record in the I/O buffer 

for processing; not valid for PUT or ERASE; valid for GET 
with OPTCD= UPD. However, to update the record, you 
must buUd a new version of the record in a work area and 
modify the request parameter list OP TCD from LOC to MVE 
before issuing a PUT. For keyed-sequential retrieval, 
modifying key fields in the I/O buffer may cause incorrect 
results for subsequent GET requests until the I/O record is 
reread. 



MVE For retrieval, VSAM moves the data record to a work area for 

processing, and for storage, VSAM moves it from the work 
area to the I/O buffer. 



Figure 13 (Part 3 of 3). OPl'CD Options 

RECLEN = number 

specifies the length, in bytes, of a data record being stored. This parameter 
is required for a PUT request. 

For GET requests, VSAM puts the length of the record retrieved in this 
field in the request parameter list. It will be there if you update and store 
the record. 



TRANSID = nw^^er 

specifics a number that relates modified buffers in a bulfer pool Used in 
shared resource applications and described in the chapter "Sharing 
Resources" in VSAM Administration Guide. 
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Example: RPL Macro 



In this example, an RPL macro is used to generate a request parameter list 
named PARMLIST. 

ACCESS ACB MACRF=( SKP , OUT) , 
J)DNAME=PAYROLL 

PARMLIST RPL ACB=ACCESS, 
AM=VSAM, 
AREA=WORK, 
AR£ALEN=125, 
ARG=SEARCH, 
MSGAREA=MESSAGE, 
MSGLEN=128, 

OPTCD=(SKP,UPD) Most OPTCD defaults are 

appropriate to assumptions. 

WORK DS CL125 

SEARCH DS CL8 
MESSAGE DS CL128 

The ACB macro named ACCESS, specifics skip-sequential retrieval for update. 
Further details may be provided on a DD statement named PAYROLL. 

The RPL macro's parameters are: 

• ACB associates the request parameter list with the access method control 
block generated by ACCLSS. 

• AREA and AREALEN specify a work area, WORK, that is 125 b>1cs long. 

« ARG specifics that the search argument is defii^ed at SEARCIi. 'Ahe search 
argument is 8 bytes long. 

• MSGARFA and MSGLEN specify a message area, MESSAGE, that is 128 
bytes long. The message area is provided for physical error messages. 

• OPTCD specifics skip-sequential processing and specifies that a retrieved 
record may be updated or deleted. 

Because KEYLEN is not coded, a full-key search is assumed. 
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SCHBFR Macro (Search Buffer) 

The fonnat of the SCHBFR macro b: 



SCHBFR 



|BFRNO = /iwm6e4 
,RFL^ address 



BFRNO = number 

specifies the number of the buffer VSAM is to search first. The buffers 
preceding it in the buffer pool are not searched. The default is I ; that is, 
the first buffer is searched first. (If the number is coded in register notation, 
all registers except 1 and 13 may be used.) 

RPL = address 

specifics the address of the request parameter list that defines the SCHBFR 
request. These RPL parameters have meaning for SCHBFR: 

ACB » address 



AREA = address 

If a buffer is found, the area whose address is specified will contain its 
address (OPTCD = LOC) or a copy of its contents (OPTCD = M VE). 

ARKALES = number 

At least 4 with OPTCD = LOC; at least control interval size with 
OPTCD =MVE. 

ARG = address 

ARG gives the address of an 8-byte field that contains the beginning 
and ending control interval RBAs of the range to be searched on. 

ECB'^ address 

OPTCD = ({ASY|SYN},{LOC jMVE}) 



TRANSID = /turner 



All other RPL parameters are ignored. RPl^ are assumed not to be 
chained. Control interval access is assumed. 

If the ACB to which the RPL is related has MACRF = GSR, the program 
that issues SCHBFR must be in supervisor state with protection key 0 to 7. 
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SHOWCB-ACB 

SHOWCB Macro (Display Fields of an Access Method Control Block) 

The fonnat of the SIIOWCB macro used to display fields in an access method 
control block is: 



|/aM 


SHOWCB 


ACB = address 






,AREA = address 






,LEN(j!TH = number 






|,0BJF:CT= I)ATA|INDEX| 






.FIELDS = (1 ACBLENI |,AVSPAC| 






|,BFRFNDI|,BSTRNO| 






|,BUFNO| 1,BUFRDS| 






|,BUFSP| 






I.CINVI |,DDNA\1E|I,ENI)RBA1 






|,ERROR| |,EXLSTI|,FS| 






|,HALCRBA| |,KEYLENI1,LRECL| 






|,MAREAI |,MLEN||,NCISi 






|,NDELR| |,NEXCI»||,NEXT| 






|,NIXL| |,M OCRl|,NRETR| 






|,NUIVV| |,NUI*DR||,PASS\VD| 






|,SHRP()OL| (,S I MS'ri|,S TRMAXI 






I,S I RNOj |,UI\\1) 



The parameters of the SMOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in re^ster notation, as S-type address 
I constants, and as indirect S-type address constants. Appendix C, "Operand 

j tN'otalion" lan l€i , further idcfines these ispcrand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the SIIOWCB 
macro. 

ACB = address 

specifies the address of the access method control block whose fields arc to 
be displayed. If you used the ACB macro with a label, you can specify the 
label here. The ACB parameter is optional when you wish to display the 
length of an access method control block (rinLDS = ACBLEN). (All 
access method control blocks have the same length, so you need not specify 
the address of a particular one.) 

AREA = address 

specifics the address of a work area that you are supplying for VSAM to 
display the contents of the fields you specify in the FIELDS parameter. 
The contents of the fields are displayed in the order in which you specify 
them. The area must be^n on a fullword boundary. 

UE2^GTH = number 

specifies the length, in bytes, of the work area that you are providing for 
VSAM to display the indicated fields in. (See the FIELDS parameter for 
the fields that can be displayed and for the length of each field.) If the area 
is not large enough for all the fields, VSAM doesn't display any of their 
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contents and returns a reason code (see "Control Block Manipulation 
Macro Return Codes and Reason Codes" on page 10). 



OBJECT" DATA ilXDEX 

specifies whether fields are to be displayed for the data or for the Index. 

FIELDS = |ACBLEN[(,AVSPACI 
|,BFRI''\D||,BSTRNO| 
|,BUFND||,BUFM| 
|,Bl^l''NO||,Bl^FRDS| 
I,BtTSl>||,CINV| 
(,DONA\fE|f,ENDRBA| 
|,ERROR||,EXLST| 
|,FS|(,HALCRBA| 
|,KEYLEN||,LRECLI 
|,i\IAREAl(,MLEN| 
(,NCIS||,NDELR| 
|,NEXCI»||,NEXT| 
iAINSR)|,NIXL| 
|,NLOGR||,NRETR| 
(,NSSS||,XLI\\1 
|,Nt'PDR||,PASS\VDI 
|,RKP||,SiIRPOOLl 
|,S'rMSTn,S'IR\IAX| 
|,STRNO||,tmD 

specifics the fields whose contents are to be displayed. Som& of the fields 
can be displayed at any time; others only after a data set is opened. Thg^ 
ones that ca n be displayed only after a data set is opened can, in the case of 
a kcv-secuenceci tiata set that h as been opened for kevcd access, p cjtain 
citncr to liie dau ui l U Ihc iiiacx. 5 cc ihc OBJECT parameter. Figure 14 
explains me Keyworas you can code in the FIELDS parameter for an access 
method control block. 



Keyword Fuilwords Description of the Held 

Note: The following fields can be displayed at any 
time. 

Length of an access method control block 
(displaying the length of an access method control 
block gives your program independence from 
chants in the length that may occur from release 
to release of VSAM) 

Number of strings initially allocated for access to 
the base cluster by a path 

Number of I/O buffers to be used for data, as 
specified in the ACB (or GENCB) 



Figure 14 (Fart I of 4). FIELDS Operand Keywords for an Access Method Control 

Block 



ACBLEN I 
BSTRNO 1 
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Keyword Fuliwords 

BUFNI 1 

BUFSP 1 

DDNAME 2 

ERROR 1 



EXLST 1 
MAREA 1 



MLEN 



PASSWD 1 



SHRPOOL 1 



STRMAX 1 
STRNO 1 



AVSPAC 1 



BFRF7VD 

BUFRUS 
CINV 



Description of the Field 

Number of I/O buffers to be used for index entries, 
as specified in the ACB (or GENCB) 

Amount of space specified in the ACB (or 
GENCB) for I/O buffers 

Name of the DD statement that identifies the data 
set 

The code returned by VSAM after the opening or 
closing of the data set (see "OPEN Macro (Connect 
Program and Data)" on page 107 and "CLOSE 
Macro (Disconnect Program and Data)" on 
page 55). 

Address of the exit list, if any; 0 if none 

Address of the message area, if any; 0 if none 

Length of the message area, if any; 0 if none 

Address of the field containing the password; the 
first byte of the field contains the length of the 
password (in binary) 

Identification number of resource pool to be used 
for LSR processing 

Maximum number of strings concurrently active 

ISIumbcr of requests for whicli VSAM is prepared 
to remember its position in the data set 

Note: llic folhming fields can be displayed only 
after the data set is opened. 

Amount of available space in the data component 
or index component, in b>tes 

Number of successful look-asides 

Number of I/O buffers actually in use for the data 
component or index component 

Number of buffer reads 

Control interval size for the data component or 
index component 



Figure 14 (Part 2 of 4). FIELDS Operand Keywords for an Access Method Control 

Block 
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Keyword Fuilwords 


Description of the Field 




Ending RBA of the space used by the dsLtsL 




component or index component; not the RBA of 




any record in the data set, but of the last used byte 




in the data set 


FS 1 


Number of free control intervals per control area in 




the data component (0 for OBJECT = INDEX) 


HALCKBA 1 


riign-allocated RBA; the relative byte address ot the 




end of the data component (OBJECT = DA TA) or 




the index component (OBJEC r= INDEX) 


KEYLEN 1 


Length of the key of reference of the key field of 




data records in the data component (whether 




OBJECT = DATA or INDEX) 


LRECL 1 


Length of data records in the data component 




(maximum length for variable-length data records) 




or of index records in the index component (control 




mterval length mmus 7) 


iNCIS 1 


Number of control intervals that have been split in 




the data component (0 for OBJECT = INDEX) 


NDELR 1 


Number of records that have been deleted from the 




dula.Gomponcat (0 for OBJECT' = INDEXy 


NEXCP 1 


Number of EXCP macros that VSAM has issued 




for access to the data component or index 




component. 


NEXT 1 


Number or extents now allocated to the data 




component or index component (the maximum 




that can be allocated in 123) 


NINSR 1 


Number of records that have been inserted into (or 




added to) the data component (0 for 




UBJbCl =iNUfcA) 


MXL i 


Number of levels in the index component (0 for 




OBJECT = DATA) 


NLOGR 1 


Number of records in the data component or index 




component 


NRETR 1 


Number of records that have ever been retrieved 




from the data component (0 for 




OBJECT = INDEX) 


NSSS 1 


Number of control areas that have been split in the 




data component (0 for OBJECT = INDEX) 



Figure 14 (Part 3 of 4). FIELDS Operand Keywords for an Access Method Control 

Block 
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Keyword 


Fullwords 


Description of the Field 


NUIW 


1 


Number of writes not initiated by the user 


NUPDR 


1 


Number of records in the data component or index 
component that have ever been updated 


RKP 


1 


Displacement of the key of reference of the key field 
from the beginning of a data record (whether 
OBJECT= DATA or INDEX) 


STMST 


2 


System time stamp, which gives the time and day of 
the last time the data component or index 
component was closed, with bit 51 (counting from 
0 at the left) equivalent to one microsecond and bits 
52 through 63 unused 


UIW 


1 


Number of user-initiated writes 



Figure 14 (Part 4 of 4). FIELDS Operand Keywords for an Access Method Control 

Block 



Example I: SHOWCB Macro (Display an Access Method Control Block) 



In this example, a SIIOWCB macro is used to display fields in an access method 
control block. The fields displayed (KEYLEN, LRECL, and RKP) permit the 
program to modify variables to process any one of a number of data sets that 
have diilcrent sized key fields and records and different placements of key field in 
a record. 

SHOWCB ACB=CONTROL, 
AREA=DI SPLAY, 
FIELDS=(KEYLEN, 
LRECL, RKP), 
LENGTH=12 



DISPLAY DS 
KEYLEN DS 
LRECL DS 
RKP DS 



OF 
F 
F 
F 



Align on fullword boimdary. 



llie SIIOWCB macro's parameters are: 



• ACB specifies the address of the access method control block to be displayed. 

• AREA specifies that the area to be used to display access method control 
block fields is to begui on a fullword boundaiy. 

• FIELDS specifies that the KEYLEN, LRECL, and RKP fields are to be 
displayed. 

• LENGTH spedfies that the length of the area to be used for the display is 12 
bytes, enou^ to accommodate the specified fields. 
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This display enables the program to set up its variables for the particular data set 
it has opened. 

Example 2: SHOWCB Macro (Display an Exit List Address) 

In this example, a SIIOWCB macro is used to get the address of an exit list by 
displaying the address in an access method control block that uses the exit list. 

SHOWCB ACB=address, 
AR£A=address , 
FIELDS=EXLST, 
LENGTH=4 

The SHOWCB macro's parameters are: 

• ACB spcciGcs the address of an access method control block from which the 
address of an exit list is to be displayed. 

• AREA and LENGTH specify an area and length, 4 bytes, to be used to 
display the address of the exit list. 

• FIl'^LDS specifies that the EXLST Held in an access method control block is 
to be displayed. 
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SHOVVCB Macro (Display Fields of an Exit List) 



The format of the SHOWCB macro used to display fields in an exit list is: 



[label\ 


SIIOWCB 


EXIST = address 






,AREA = address 






,LE\GTH = number 






,FIELDS=(|EODAD| |,EXLLEN| |,JRNADI 






|,LERA1)||,SYNA1)|) 



The subparamctcrs of the SIIOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in re^ster notation, as S-typc address 
I constants, and as indirect S-type address constants. Appendix C, "Operand 

I Notation" on page 181, further dcfmes these operand expressions. 

labei 

is 1 to 8 characters that provide a symbolic address for the SIIOWCB 
macro. 

EXLSi:^ address 

specifics the address of the exit list whose fields are to be displayed. If you 
used the EXLST macro with a label, you can specify the label here. The 
EXLST parameter is optional only when you want to display the length 
that an exit list can have (see FlliLDS = EXIXEN below). The SI lOWCB 
macro does not support the IJPAD user exit. 

AREA = address 

specifics the address of a work area that you arc supplying for VSAM to 
display the contents of the fields you specify in the FIELDS parameter. 
The contents of the fields arc displayed in the order you specify them. The 
area must begin on a fuUword boundary. 

LENGTH = number 

specifies the length, in bytes, of the work area that you are providing for 
VSAM to display the indicated fields in. Each exit-list field requires a 
fullword. If the area is not large enough for all the fields, VSAM doesn't 
display any of their contents and returns an error code (sec "Control Block 
Manipulation Macro Return Codes and Reason Codes" on page 10). 

FIELDS « (|E()DAI)1|,EXLLEN|MRN Al)| 
|,LERAI)1I,SYNAI)I) 

specifies the values to be displayed, as follows: 
EODAD 

specifies that the address of the end-of-data-set routine is to be 
displayed. 

EXLLEN 

specifies that the length of the exit list indicated in the EXLST 
parameter or if EXLST is omitted, the maximum length an exit 
length can have, is to be displayed. 
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JRNAD 

specifies that the address of the journalizing routine is to be displayed. 
LERAD 

specifies that the address of the logical error analysis routine is to be 
displayed. 

SYNAD 

specifies that the address of the physical error analysis routine is to be 
displayed. 

You can use SIIOVVCB to display the address of an exit routine only if the exit 
routine is indicated in the exit list. If it isn't, the SIIOWCB request will fail. Use 
TESTCB to test whether an entry for a given exit type is present in the exit list 
and to find out whether the exit is active and whether the routine is to be loaded. 



Example: StIOWCB Macro (Display the Length of an Exit List) 



In this example, a SIIOWCB macro is used to display the maximum length of an 
exit list. I1ie maximum length of an exit Ust is subsequently used in a GENCB 
macro to get virtual storage for an exit list. 

SHOWCB AREA=LENGTH, 

FIELDS=EXLLEN, 
LENGTH=4 



L 0, LENGTH 

GETMAIN R,LV=(0) 
LR 2,1 



GENCB 



BLK=EXLST, 
LENGTH=(*, 
LENGTH) , 
WAREA=(2) 



Amount of storage for 
GETMAIN. 



Address of storage for 
GENGB. 

Indirect notation for 
length of work area. 



LENGTH DS 



Contains the length of 
GENCB * s work area . 



The SHOWCB macro's parameters arc: 

• AREA and LENGTH specify the area, which begins on a fuUword 
boundary, and its length, four bytes, that is to be used for the display. 

• FIELDS specifies that the maximum length of an exit list is to be displayed. 
Because only EXLLEN is specified, the EXLST parameter is omitted. 

The GENCB macro specifies a work area in which an exit list is to be generated. 
The length of the work area is located at LENGTH, where the maximum length 
of an exit list was put as a result of the SHOWCB macro. 
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SHOWCB Macro (Display Fields of a Request Parameter List) 

The fonnat of the SHOWCB macro used to display fields in a request parameter 
list is: 







I\I i-rf UCiClrcoj ' 






fAREA = address 






jLENGTH = number 






.FIELDS = (|ACBj|,AIXFC||,AREAI|,AREALEN| 






|,ARG||,ECB|l,FI)BKl|,FrNCl)l 






|,KEYLENI|,MSGAREA| 






|,MSGLEN| 






|,NXTRI>L||,RBA| 






|,RECLEN| 






|,RFLLEN| 






|,TRANSID|) 



The parameters of the SHOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-type address 
I constants, and as indirect S-type address constants. Appendix C, "Operand 

I Notation" on page 1 8 1 , further defines these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the SIIOWCB 
macro. 

RPL = address 

specifics the address of the request parameter list whose fields are to be 
displayed. If you used the RPI. macro with a label, you can specify the 
label here. The RPL parameter is optional when you want to display the 
length of a request parameter list (MELDS = RPLLEN). (All VSAM 
request parameter lists have the same length, so you need not specify the 
address of a particular one.) 

AREA - address 

specifics the address of a work area that you arc supplying for VSAM to 
display the contents of the ficld.s you specify in the FIlvLDS parameter. 
The contents of the fields arc displayed in the order you specify them. The 
area must bc{pn on a fullword boundary. 

LENGTH = number 

specifics the length, in bytes, of the work area that you arc providing for 
VSAM to display the indicated fields in. Each request parameter list field 
requires a fullword. If the area is not large enough for all the fields, VSAM 
doesn't display any of their contents and returns an error code (see 
"Control Block Manipulation Macro Return Codes and Reason Codes" on 
page 10). 
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HELDS = (lACBIf ,AIXPCI|,AREAI|,AREALEN||^RG| 
|,ECB|[,FDBK|I,FTNCDII,KEYLENI 
|,MSGAREA||,MSGLENI 
|,NXTRPL||,RBA|I,RECLENI 
|,RPLLEN|I,TRANSIDD 

specifics the fields whose contents arc to be displayed. Figure 15 on 
pa^ 142 explains the keywords you can code in the FIELDS parameter for 
a request parameter list. Some fields (each indicated by an asterisk {*) in 
Figure 15) are meaningful only if the requests have been completed; 
therefore, you must wait until the request has completed (for example, by 
issuing a CHECK if the request is asynchronous) before issuing SI lOWCB. 



Keyword 
ACB 

AIXPC* 
AREA 

AREALEN 

ARC 

ECB* 

FDBK* 



Fullwords Description of the Field 



Address of the access method control block that 
relates the request parameter list to the data 

Number of alternate index pointers 

Address of the work area that the program uses to 
process a data record for the access as defined by 
the request parameter list 

Length of the work area whose address is given in 
AREA 

Address of the field containing a search argument, 
if search- arguments are being mad 

Address of an event control block, if any, in which 
VSAM indicates the completion of requests 
defined by the request parameter list 

Reason code that VSAM puts into the feedback 
field to describe the error detected for the 
precc(&ig request. (The meaning of this code 
depends on the contents of register 15, which 
indicates whether the request was successful or 
failed because of a logicaJ or physical error. See 
"Record Management Return Codes and Reason 
Codes" on page 13) 

Code that describes the function in which a lo^cal 
or physical error occurred; indicates whether the 
upgrade set may have been modified incorrectly by 
the preceding request (The meaning of this code 
depends on the contents of register 15, which 
indicates whether the request was successful or 
failed because of a logical or physical error. See 
"Record Management Return Codes and Reason 
Codes" on page 13) 



Figure IS (Part I of 2). FIELDS Operand Keywords for a Display Request Parameter 

List 
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Keyword Fullwords 

KEYLEN 1 

MSGAREA* 1 

MSGLEN 1 

NXTRPL 1 



RBA' 



1 



RECLEN* 1 

RPLLEN 1 
TRANSID 1 



Description of the Field 

Length of the search argument, if a generic key is 
used for a search argument 

Address of the area, if any, into which VSAM puts 
physical error messages 

Length of the message area, if any 

Address of the next request parameter list, if 
another one is chained to this one 

Relative byte address of the most recently 
processed record; you could use it to record the 
RBAs of records that you arc retrieving or storing 
sequentially or by key 

Length of the data record, access to which is 
defined by the request parameter list 

Length of a request parameter list 

Number that relates modified buffers in a buffer 
pool; described in VSAM Administration Guide 



Figure 15 (l*art 2 of 2). FIKLDS Operand Keywords for a Display Request l*aramctcr 

List 
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Example: SIIOWCB Macro (Display a Physical Error Message) 



In this example, a SHOWCB macro is used to display a physical error message. 
This example assumes that there is no SYNAD routine (or the SYNAD exit is 
inactive), in which case, VSAM returns control to your program following the 
last executable instruction if a physical error occurs. Register 15 indicates a 
physical error (12), and the feedback field in the request parameter list contains a 
code identifying the error; the message area contains more details about the error. 
Register 1 points to the request parameter list. 



REQUEST RPL 



MSGAR£A= 

MESSAGES, 

MSGLEN=:128 



SHOWCB AREA=MSGADDR, 

FIELDS=MSGAREA, 

LENGTH=4, 

RPL=REQUEST 

LTR 15,15 

BNZ CHECKO 



CHECKO 



Display failed. 



MESSAGES DS 



MSGADDR DS 



CL128 



For VSAM to give you a 
detailed message about 
a physical error. 

For displaying the 
address of the message 
area with SHOWCB. 



The RPL macro in this example provides for a message area, MESSAGES, of 
128 bytes to be used for any physical error message. 

The SHOWCB macro's parameters are: 

• AREA and LENGTH specify a 4-bytc area, MSGADDR, to be used for 
displaying the address of the message area for the associated request 
parameter list. 

• I'lELDS specifies that the address of the messa^ area is to be displayed. 



RPL specifies the name, REQUEST, of the request parameter list for which 
the message area address is to be displayed. 
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I TESTCB Macro (Test Fields of an Access Method Control Block) 

Only one keyword can be specified each time you issue TESTCB. The format of 
the TESTCB macro used to test a field in an access method control block is: 





TK^TfR 


t\\^ D UUUrKSS 












1 1111 ii-'PT= 11 ATA irvni-'vi 






f AXDU — /'llTCIICIi LTCIICII 1 HCII DI<^PI 1 
A 1 KIS — ^l!<3L/:^||,K3L/3|i,l'lid||,Kr<l L.J 






1 DDIICIi CP A VII CCVV^IIil wr'ifii 






AXDR — ITVr^l 
A 1 Kd — UlNvl 






CAIALvHjr— illoirNv>| 






CKA = !>l,KA|L'i-KAI 






n't A /^Dir — /I A I1DII Alvii /"*i.*vii r^vvii I'^nvTi 
I\lAi.Kr = (|Al/Kl|,AlA||,l..r A||,CrN V||,liL/r>| 






1 rtiroii T\TDii r^cx7ii r^cDit ir^tii rvi 






"1 i/'irvii 1 CDii Mr^iii x!L'r>ii virvii vici 
|,KbY||,LaK||,i\Cl||,rNrli||,rSr A||,rNlc>I 






1 ,IN K iM 11 rs Kc> Jl ,i> 11 ,i\ tJ l>ll ,tl U 1 II ,Ka 1 J 






1 d?/\ii cicii cimii imt/ivi 
|,ShQ||,SIS||,SKP||,UBb|)| 












Ul trSvJixJ — i'Alli|t>Abr.iAIA| 






ALlSLr<r\ = numoer] 






AVNI AC = numoeri 












ISUriNL/ = niunoer\ 






BU r IM = nuntberx 






DUr iNiJ = numoeri 






BUr?>l — nunwerx 






v,llN V — itunwer\ 












Ei* VI ID DA — MKmA/x-i 






r.KKi/K — nw7W€r\ 






KjS-Uj 1 auuress\ 






tS — nufnber\ 






IVC< I LiC<;^ — nUrnO€r\ 






JL<K.I!<\^JL< — nuiTioer\ 






\f ADIT A s: /i///Vr0cci 






iTiL>c<i^ numucf \ 






'KC\*s — numht>r\ 






NDFI R s numberX 


















NINSR = /iMm6er| 






NIXL»/ii/wM 






NLOGR = /i«mM 






NRKTR = m<mM 






NSSS = n«mM 






NUPDR = nwm6er| 






PASSED = a£/(/re«| 






RKP = nMm6er| 






SHRPOOL=/2umM 






STMST = a<frfrejj| 






STRNO = ra/m^er} 
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The subparameters of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

XC^- address 

specifies the address of the access method control block whose information 
you want to test. You may omit it only if you're testing the length of an 
access method control block (ACBLEN = number). (All VSAM access 
method control blocks have the same length.) 

TJtLEIT address 

specifies the address of a routine to which VSAM is to give control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access method control block for an 
unopened data set would fail. VSAM indicates in register 15 whether it 
could do the test and, if not, indicates in register 0 the reason it couldn't, 
(llie reasons are discussed under "Control Block Manipulation Macro 
Return Codes and Reason Codes" on page 10.) \ failure trying to execute 
THSTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an ABEND. If it lets the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 

OBJECT = DATA IIXDEXi 

specifies whether you want to test a field for data or for index. 

ATRB = (1ESDS||,KSDS1|,LDS| 
I.REPLI 
|,RRDS| 
|,SPAN| 
|,SS\\1)| 
|,WCKD 

specifies, for an open data set, the attribute that is to be tested for, as 
follows: 

ESDS 

entiy-sequenced data set 

KSDS 

kcy-sequenced data set 

LDS 

linear data set 

Note: When specified, LDS must be the only parameter indicated by 
ATRB. All other parameters will be ignored and a binary test will be 
performed that indicates whether the data set is a linear data set 
(return code 0) or not (return code 1). 
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REPL 

some portion of the index is replicated 

RRDS 

relative record data set 

SPAN 

data set contains spanned records 
SSWD 

sequence set is adjacent to the data 

WCK 

write operations for the data set arc being verified 
ATRB=UNQ 

specifies, for an open alternate index or path, that the alternate index 
requires unique keys, llie test for Al RB = UNQ must be made with a 
separate TliSTCB macro. VSAM examines the path control blocks for the 
UNQ attribute; and also examines the base cluster's control blocks for the 
other attributes. If other attributes are tested for, VSAM examines, the base 
cluster's control blocks for all attributes: The test for A rRB= UNQ would 
give inaccurate results when applied to the base cluster's control blocks. 

CATALOG = YES|NO 

specifies that a test is to be made to determine, any time, whether or not 
the access method control block specifies a catalog data set. 

CRA = SCRA|UCRA 

specifics that a test is lo he made to determine, any time, whether catalog 
recovery area control blocks are to be built in system storage or user 
storage. 

M ACRF = (|ADR|(,AIX1|,CFX| 
|,CNV|I,1>DN| 
|,DFR||,DIR1 
|,DSN|[,GSR1 
|,ICI1|,INI 
(,KEY|I,LSRI 
|,Nd||,Nl)F| 
|,NFX||,NIS| 

l,NR^^I^NRS| 

|,NSR1|,NUB| 
|,OUl||,RSIl 
|,SEO|(,SISI 
|3KP||,UBF| 

specifies that a test is to be made to determine, at any time, what 
subparamctcr or combination of subparameters is being used for processing. 

OFLAGS = OPEN 

specifies that a test is to be made to determine, after open, whether the data 
set identified by the control block has been opened. 
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OPENOBJ = PATH|BASE|AIX 

specifies that a test is to be made to determine, after open, whether an 
opened object is a path, a base cluster, or an alternate index. 

The remaining parameters represent fields in an access method control block that 
can be compared with the value specified. These fields arc the same as those that 
can be displayed by using the SIIOWCB macro and are described in Figure 14 
onpa^ 134. 

If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don't alter the 
PSW condition code that VSAM set to indicate the result of a test until you've 
had a chance to test it. 



Example: 1 ESTCB Macro (Test for Data Set Attributes) 



In this example, a TESTCB macro is used to determine whether a data set is a 
key sequenced or an entry-sequenced data set. 



LIST 



RPL 



SHOWCB AREA=DATAFACT, 
FIELDS=ACB, 
LENGTH=4, 
RPL=LIST 



LTR 
BNZ 



15^15 
CHECKO 



TESTCB ACB=(*, 

DATAFACT) , 
ATRB=KSDS, 
ERET=CHECKO 



BE 



KEYSEQ 



KEYSEQ 
CHECKO 



DATAFACT DS 



Is the data set key 
sequenced? 



Yes. 

Data set is key sequenced. 
Display or test failed. 



For displaying address of 
access method control 
block. 



The SHOWCB macro's parameters are: 

• AREA and LENGTH specify a 4-byte area, DATAFACT, aligned on a 
fullword boundary, to be used for the display. 

• FIELDS and RPL specify that the address of the access method control 
block in the LIST request parameter list is to be displayed. 

The TESTCB macro's parameters are: 



148 MVS/XA VSAM Administration: Macro Instruction Reference 



TESTCB-ACB 



• ACB specifics that a field in the access method control block, the address of 
which is located at DATAFACT, is to be tested. The SHOWCB macro put 
the address of the access method control block at DATAFACT. 

• ATRB specifies that the access method control block is to be tested to 
determine whether it is a key-scquenccd data set. 

• ERET specifies that a routine named CIIECKO is to be given control if an 
error occurs that makes it impossible to make the test. 

There is no need to examine the feedback field in an EODAD routine, because it 
can be assumed to contain the end-of-data-set indication. 
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TESTCB Macro (Test Fields of an Exit List) 



The format of the TESTCB macro used to test fields in an exit list is: 





TESTCB 


EXLST » address 






lERET' address] 






,(EODAD - {0|(|d^</reu||,A|Nl|,LD) i 






JRNAD= {0|(M^/rMj|I,A|N||,LI))l 






LERAD - {0|(M^reij||,A|NH,M)]| 






SYNAD- {O|(MJrejj|i,A|N||,L0)) 






lEXLLEN^ number] 



The parameters of the TESTCB macro can be expressed as absolute numeric 
expressions^ as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-typc address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

label 

is 1 to S characters that provide a symbolic address for the I'ES'l'CB macro. 
EXLSt = address 

specifies the address of the exit list whose information you want to test. 
You may omit it only if you're testing the maximum length of an exit list 
(EXLLEN=numb€r)«^ The TESTCB macm does not su^^pert the UPAD 
user exit. 

ERET == address 

specifics the address of a routine to which VSAM is to ^ve control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access method control block for an 
unopened data set would fail. VSAM indicates in rc^ster 15 whether it 
could do the test and, if not, indicates in register 0 the reason it couldn't. 
(The reasons are discussed under "Control Block Manipulation Macro 
Return Codes and Reason Codes" on page 10.) A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an ABEND. If it lets the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 

EODAD - [0\{\address\lA\^\iX\}] I 

JRNAl) » {0|(lae/Jrejjj|,A|N||,L|» i 

LERAD ^ [maddress\l\\MAW 

SYNAD = [0\{{address\\M^[lL\)} 

specifies the exit about which you arc asking a yes-no question. If you 
code more than one parameter for an exit name, each must equal the 
corresponding value in the control block for you to get an equal condition. 
The values that can be tested are: 

0 

specifies that a test is to be made to determine whether an entry is 
provided for the exit in the exit list. 
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address 

specifies that a test is to be made to determine whether this is the 
address of the exit. Tests for an address result in an equal, unequal, 
high, low, not-high, or not-low condition. Tests for a combination of 
an address and A, N, or L resuh in an equal or unequal condition. 

AIN 

specifies that a test is to be made to determine whether an exit is 
active (A) or not active (N). Tests for A or N resuh in an equal or 
unequal condition. 

L 

specifics that a test is to be made to determine whether the address is 
the location of an 8-byte field containing the name of a module to be 
loaded rather than the entry point of the routine. Tests for L result in 
either an equal or unequal condition. 

EXLLEN « number 

specifics either the maximum length that an exit list can have (if you don't 
code the IsXI^T parameter) or the actual length of the exit list indicated by 
the liXIiJT parameter. If you specify an exit, you may not also specify 
EXLLEN; if you specify EXLLEN, you may not also specify an exit. 

If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch tabic, for example, but don't ahcr the 
PSW condition code that VSAM set to indicate the result of a test until you've 
had a chance to test it. 

Example: IICSTCB Macro (Use a ikanch Tabic) 

In this example, a TESTCB macro is used to test whether ENDPROC is the 
routine supplied for the EODAD exit in the exit list EXITS, and whether the 
EODAD exit is active. A branch table is used to determine whether the test is 
successful. 

TESTCB EODAD=(ENDPROC,A) Is ENDPROC supplied and is 

EXLST^EXITS the exit active? 

B *+4(15) 

If the test was made successfully, register 15 contains 0 and the next instruction is 
executed. 

B TESTl 

If it was unsuccessful, register 15 contains 4 and the next instruction is executed. 

ABEND 2, DUMP 
HESTl BNE NO 

YES ... Yes; ENDPROC is supplied 

and active. 

NO ... ENDPROC isn't supplied, or 

the exit isn't active. 
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TESTCB Macro (Test a Request Parameter List) 



The format of the TESTCB macro to test fields in a request parameter list is: 



[iabeli 


TESTCB 


RPL = address 






lERVJ '^addressl 






,{AIXFLAC = AIXPKP| 






AIXPC = /zMmM 






VVNCD = number\ 






IO=C()MPmE| 






OPTCD = (|ADR|(,ARD|I,ASY||,BWDI 






l,CNV||,DIR|I,FKS|l,nVD| 






I,GEN||,KEQl|,KEYI|,KGE||,LOC| 






|,LRI)|I,MVE1|,NSP|I,NLP||,SEQ| 






(,SKP|1,SYN||,UPD1)| 






\CB = address\ 






AREA = address] 






AREAtVJS = number\ 






\RG = address] 






ECli = address] 






VDHK^ number] 






KEYLES^ number] 






MSGAREA = address] 






MS(»LEN = number] 






yiXTRPL^ addressi 






RBA = number] 






REChES^ number] 






RVLLEN-' number] 






TRASSID-- number] 



The parameters of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

where: 

label 

is 1 to 8 characters that provide a symboUc address for the TESTCB macro. 
RVL= address 

specifies the address of the request parameter list whose information you 
want to test. You may omit it only if you're testing the length of a request 
parameter list (RPLLEN = number). (All request parameter lists have the 
same length.) 

ERET address 

specifies the address of a routine to which VSAM is to give control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access method control block for an 
unopened data set would fail. VSAM indicates in register 15 whether it 
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TESTCB-RPL 



could do the test and, if not, indicates in register 0 the reason it couldn't. 
(The reasons are discussed under "Control Block Manipulation Macro 
Return Codes and Reason Codes" on page 10.) A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an abend. If it lets the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 

AIXITAG = AIXPKP 

specifics that prime-key pointers are used rather than RBAs. 

\l\PC'= number 

specifics the pointer count. 

FTNCI) = number 

specifies whether the upgrade set is correct or may have been modified by a 
request. These codes are described under "Component Codes 
(RPLCMPON)" on page 14. 

IO = CO.MPLETE 

specifics that a test is to be made to determine whether an asynchronous 
request has been completed. (When you issue a CIIISCK macro, you 
suspend processing until a request has been completed if it hasn't yet been 
completed.) 

OP TCD = (|,ADR||,ARDI|,ASY|I,BVV1)||,CN\ ||,D1R|1,FKS| 

|,F\V1)I|,GEN||,KEQ1I,KEY||,KGK1I,L()C1I,I.RD1 

|,M\E||,NSPlI,NLP||,SEQ|l,SKPl|,SVMI,t'PI)l 
specifies that a test is to be made to determine what subparamctcr or 
comtsinatioti of subparamctta-s is being used for the request. See Figure 17 
on page 184 for a description of these -subparameters. 

1 he remaining parameters specify fields m a request parameter list and values; the 
contents of a field are to be compared to the specified value. These fields are the 
same as those that can be displayed by using a SIIOVVCB macro. (See Figure 15 
on page 142 for an explanation of these fields.) Fields can be tested at the same 
time they are displayed. 

You may specify only one keyword. If you code a list of option codes (for 
example, OP rCD = (KEY.DIR)), each of them must equal the corresponding 
value in the control block for you to get an equal condition. 

If you omit a routine to handle error conditions, you can examine re^ster 15 
following TFSTCB by using a branch table, for example, but don't alter the 
PSW condition code that VSAM set to indicate the resuh of a test until you've 
had a chance to test it. 
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Example: TESTCB Macro (Test a Request Parameter List) 



TESTCB RPL=(3), 
RECLENsSO 



BE 



N0CHN6E 



CHANGE 



Because the record length in 
the request parameter list was 



not 80, the length indicator 
must be modified so that it 
is 80. 



N0CHN6E 



Because the record length in 
the request parameter list was 
80, no change is required. 



The TESTCB macro's parameters arc: 

• RVL specifics that the address of the request parameter list to be tested is 
contained in register 3. 

• RECLHN specifics that the record length indicated in the request parameter 
list is to be tested to determine whether it is 80. 
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VERIFY Macro (Synchronize End of Data) 



VERIFY 



The fonnat of the VERIFY macro is: 



\labeli 


VERIFY 


RVL'^ address 






|,ACTION-REFR(:SII| 



where: 



label 

is 1 to 8 characters that provide a symbolic address for the VERIFY macro. 
RPL'^ address 

specifies the address of the request parameter list that defines this VERIFY 
request. You may specify the address in rc^stcr notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-type address constant. 

The following parameter and subparameter arc required for VERIFY: 

In the RPL, OPTCD = <CNV,...) must be specified. 

ACTION « REFRESH 

specifies that the VSAM control blocks are to be updated from the catalog 
after an attempt has been made to verify the high-used RBA. For a data 
set that has been extended, VERIFY with AC riON= REFRESH will 
invoke end of volume processing to update the control block structure, 
rcficciingthe new extents. 

If you do not specify ACriON= REFRESH for an extended data set, you must 
close the data set and reopen it to obtain new extent information before you can 
verify it. 

I Any attempt to issue the VERIFY macro against a linear data set (EDS) will 

i result in a logical error (rctum code 253 in the feedback field of the RPL). 

After verifying a data set, positioning must be established with a POINT macro 
or with a GET macro with RPL OPTCD = DIR. 
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WRTBFR 

VVRTBFR Macro (Write Buffer) 

The format of the WRTBFR macro is: 



WRTBFR 



RPL^ address 

,TYPE-{ALL|CHK|DRBA|DS|LRU(perce/iO|TRN} 



RPL'' address 

specifies the address of the request parameter list that defines the WRTBFR 
request. An RPL need not be built especially for the 
WRTBFR— WRTBFR may use an inactive RPL that defines other 
rcquest(s) (GET, PUT, and so forth) for a data set that is using the 
resource pool. The following RPL parameters have meaning for 
WRTBFR: 



ACB = address 
ARG = address 

For TYPE== DRBA, the address of a 4-byte field that contains the 
RBA to be located and written. 

ECB address 



OPTCD={ASY|SYN) 

WRTBFR can be issued synchronously (SYN) or asynchronously 
(ASYJ- A CIIECXor ENDREQ must be issued to synchronize an 
asynchronous WRTBFR request. 

JRXSSID^ number 

Specifies a number from 0 to 31. 

All other RPL parameters arc ignored. RPLs are assumed not to be 
chained. 



If the ACB to which the RPL is related has MACRF = GSR, the program 
that issues WRTBFR must be in supervisor state with protection key 0 to 
7. 



TYPE={ALL|CIIK|I)RBA|!>S|LRU(perce/zO|TRN) 
specifies which buffers are to be written. 

Note: Before using WRTBFR TYPE = CHKIDRBAfrRN, be sure to 
release all buffers. VSAM defers processing until all buffers are released. 
For details about releasing buffers, see VSAM Administration^ 

ALL 

specifies that all modified unwritten index and data buffers in each 
buffer pool in the resource pool are to be written. No buffers will be 
invalidated. Closing all the data sets that use a resource pool causes 
the same buffers to be written. 
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WRTBFR 



CHK 

is as TRN (below), but, if an error occurs in writing buffers, 
transaction IDs continue to be associated with the buffers. 
WRTBFR TYPE = CHK could be used by a checkpoint routine to 
record checkpoint information and leave buffers for which an error 
occurred as they were for continued processing. 

DRBA 

specifics that one of the data set's data buffers is to be written. The 
buffer to be written is. identified with the RBA pointed to by the RPL 
ARC address. 

DS 

specifies that, for the data set defined by the ACB to which the 
WRTBFR's RPL is related, all modified unwritten index and data 
buffers are to be written and all buffers are to be marked empty, i.e., 
invalidated. Therefore, WRTBFR TYPE = DS should be issued only 
after all VSAM requests for the data set have been quiesced. 
Otherwise, unpredictable results may occur. 

LRVipercent) 

specifies that some of the modified buffers in each buffer pool in the 
resource pool are to be written. The percent is the percentage of 
buffers in each pool that are to be examined for possible writing. Ths 
least recently used buffers are examined. (If percent is coded in 
register notation, only registers 1 and 13 may not be used.) 

TYPE = LRU is used for writing some modified buffers, without 
-Kspccl loa^aarticular jdala set or transaction ID, to ensure that 
buffers will be available for GET requests (without having to wait for 
buffers to be written). 

TRN 

specifies that all buffers in a buffer ix)ol that have been modified by 
requests with the transaction ID specified in the WRTBFR's RPL are 
to be written. Transaction IDs are no longer associated with these 
buffers if WRTBFR completes successfully. 
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I 



Appendix A. Format of Macros 



For easy reference, the formats of all the macros described in this book are 
repeated here in alphabetic order. 

ACB (Generate an Access Method Control Block at Assembly lime) 



[labeii 


ALB 


lAiM = VaAIVll 






\yoS 1 KiSi/ ■= number\ 






|,i5ljr NU = numbery 






|,BuriM number} 






|,lll;r 51' ~ number] 






|,CATALOG = {YES|NO}| 






|,CRA={SCRA|UCRA}| 






IDDWME'-ddnamel 






IVXlSr-- address] 






|,MACRF = (fADRIi.GNVH.KEYI 






I.CFXINFXI 






I.DDNIDSNj 






|,D>'R|M)FJ 






|,DIR||,SE21I,SKP| 






|,ICI|NCI| 






|,!N|l,OUT| 






|,MS|SIS| 






|,NRM|AIX| 






|,NRS|RS11 






|,NSRiLSR|GSRJ 






I,NIJB|UBF|)| 






|,MAREA = aJi/rew| 






|,MLEN = /ittm£»ei 






[JPASSWD'oddressl 






i.RMODE3l « (ALLIBUFFICBINONEM 






|,SIIRPOOL« (0|m/m6er)| 






l^STKSO" number] 



ACQRANGE (Stage Data) 



llabeli ACQRANGE RPL^ address 



Appendix A. Format of Macros 



BLDVRP (Build a VSAM Resource Pool) 



BLDVRP 


BUFFERS = {size{number)^ize{nwnber}f...) 




|,FIX= {BFR|IOB|(BFR,IOB)]| 




|,KEYLEN = fe/i^//t| 




I,RMODE3l = fALLIBUFFICBINONEll 




ISHRPOOL^ {0\number]\ 




I,MODE={24!37}| 




ySTRNO^ number 




l,TYPE= fLSRI.DATAiINDEXIIGSR)l 



CHECK (Suspend Processing) 



\label[ CHECK RPL = address 



CLOSE (Disconnect Program and Data) 



\Iahei[ 


CLOSE 


(address\,(options)\...\ 






|,MODE»{24|3l)| 






I,TYPE»T| 



CNVTAD (Convert Address) 



\label\ 



CNVFAD RVL^- address 



DIA'RP (Delete VSAM Resource Pool) 



DLVRP 



TYPE={LSRiGSR) 
|,MODE={24|3I|| 
|,SHRPOOL= {0\number]] 



ENDREQ (Terminate a Request) 



[label^ ENDREQ RPL^ address 



ERASE (Delete a Record) 



{iabel[ 



ERASE 



R?L^ address 
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EXLST (Generate an Exit List at Assembly Hme) 



[labels 


EXLST 


|AM = VSAM| 






|,EODAD = {addres4,A\MyU)\ 






IIOPID^ (address)] 






I^RNAD = {address[,\\^\m)\ 






|,LERAD » (address\A\MM)\ 






I^YNAD = (addresslMMX])] 






|,UPAD = (addressiMWDl 



GENCB (Generate an Access Method Control Block at Execution Time) 



\iabel\ 


GENCB 


BLK-ACB 






I.AM = VSAMI 






{.BSTRNO ^ number] 






|,BUFND = number] 






IBVFNl^ number] 






IBVFSP'^ number] 






|,CATALOG= {YES|NO)| 






ICOPIVS-- number] 






|,CRA= {SCRA|UCRA}| 






IDDMAME'- ddname] 






lEXLST-- address] 






ILE^GTll = number] 






l,LOC= fBELOWIANYII 






1 IVf A f^D IT — /I A IIP il r'MVII KTVI 






|,CFX|NFX| 






I,ODN|f>SNi j 






LDFRINDFI 






I,I)IR||,SE9||,SKP| 






I.ICIiNCn 






|,INII,OUTJ 






|,NISiSIS| 






|,NRM|AIXI 






|,NRS|RST| 






(,NSR|LSR1 






KNUBILBFDI 






IMAREA'^ address] 






|,M LEN = number] 






IP ASSWD^ address] 






I.RMODE3! = fALLIBUFFICBINONEH 






|,SHRPOOL= I0\number}] 






address] 






IWAREA''^ address] 
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GENCB (Generate an Exit List at Execution Time) 







RI IT a ITYI CT 






1 Al\/f as VQA Vfl 






ICOPIES'' number] 






|,EODAD = (address[,A\>l\lL\)\ 






MRxNAD = iaddressl,A\S\iXl>\ 






|,LENGTH = numbeii 






|,LER AD > {addressl,A\N\lLD\ 






IXOC=fBELOVVIANY] 






I^YNAD » {address\A\MXd\ 






IWAREA-^ address]" 



GENCB (Generate a Request Parameter List at Execution lime) 



\labei\ 


GENCB 


BLK = RPL 






I^CB = address] 






l,AM-VSAMI 






|,AREA = address] 






1 ARF AI FN — iminheri 






lARG- address] 






[yCOPlES^ number] 






address] 






IKEYLEN^ number] 






^ ILE^GfH^' numberf 






I,LOC= fBELOWIANY)! 






1,MSGARE A = address] 






IMSGLES-' number] 






INXJRPL^- address] 






I.OPTCD = (IAI)R|CNV| KEYI 






LDIRiSEQISKPi 






|,ARDiLRD| 






1,^1)1 BWD| 






I,ASY|SYN| 






i;VSP|NUP|UPD| 






|,KEQ|KGE| 






(,FKS|GEN| 






|,LOC|MVE|)| 






{^ECLFN^ number] 






(,TRANSID = /n/mi5>efl 






IWAREA'- addresA 



GET (Retrieve a Record) 



]label] 



GET 



R^h'' address 
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GETIX (Retrieve am Index Record) 



\labeli GETIX RPL = address 



MNTACQ (Mount Acquire) 



I \iabel\ I MNTACQ [ RVL^ address 



MODCB (Modify an Access Method Control Block) 



[labeli 


MODCB 


ACB = address 






|,BSTRNO = «wm6erl 






inVFSD^ number] 






IBVIKI=- number] 






IBVhSV^ number] 






|,CATALOG = {VES|NO}| 






1,CRA={SCRA|LCRA)| 






IDD\AME= ddname] 






|,LXLS I » address} 






|,M ACRF = (1 ADR|I,CNV||,KEY| 






I,CFX|\FXI 






|,DDN|DSN| 






I,DFRjNDF| 






|,I)IR||,SEQ||,SKP| 






|,ICI|NCI1 






t,fNl|,«l;T| 






|,MS|SISI 






I,NRM|AIX| 






|,NRS|RS11 






|,NSR|LSRI 






|,NUBlUBn)| 






IMAREA^ address] 






IMLEN^ number] 






IPASSWD'^ address] 






I.RMODE3I = (ALLIBUFFICBINONFJI 






ISURIH^OL'^ number] 






ISTRSO^ number] 



MODCB (Modify an Exit Ust) 



[label] 


MODCB 


KKLST^ address 






|,EODAD = {address\M^^X\)] 






I^IRNAD = iaddress\,A\S]]X\)\ 






|,LERAD = iaddress\,A\N]m)] 






1,SYNAD = iaddress],A\MM)] 
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MODCB (Modify a Request Parameter List) 



{Iabel\ 


MODCB 


RFL^ address 






[yACB^ addressi 






j,AREA =» addres^ 






|,AREALEN = number] 






lA^G'^ address] 






IJlCE^ address] 






|,KEYLEiN*/T«mAcr| 






i,i\ISGAREA » address] 






IMSGLEN'- number] 






INX'IRVL^ address] 






|,01*TCD - (lADRjCNVI KEYJ 






{,ARD|LRD| 






|,RVD|B\VD| 






[,lilK|SbQi3Kr| 






[,ASY|SYN| 






|,NSP|NLP|UPD| 






|,KEQ|KGE| 






|,FKS|GEN| 






I,LOC|MVE|) 






|,RECLEN = /iw/w6e/i 






1, TR ANSID = number] 



MRKBFR (Write Buflcr) 



MRKBFR 



MARK= {DINVAUD|XINVAlJI)|Oin IRLS} 
,RPL = address 



OPEN (Connect Program and Data) 





]label] 


OPEN 


{addres^y{options)].,.) 
|,MODE={24|3l}| 


POINT (Position for Access) 




]iabel] 


POINT 


R?L = address 


PUT (Store a Record) 










]iabel] 


PUT 


RVL- address 
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PUnX (Store an Index Record) 

[Iabe/[ [ PtniX \rVL= address 
RPL (Generate a Request Parameter List at Assembly Time) 



\label\ 


RPL 


ACB = address 






|,AIVI = VSAMI 






|,AREA » address] 






1, AREALEN = number] 






I^ARG = address] 






\,E^B'^ address] 






|,KEYLEN = number] 






|,MSG AREA » address] 






|,MSGLEN = /ium^/i 






1 VYTDPI = nf1/1r0tt\ 

I i\i Li ~ uaaressj 






|,OPTCD = (lADRICNTiKEYI 






IJ)IRiSEOISKPl 






|,AR1)|I.RD| 






|,E\VI)|BWI)| 






|,ASYiSVN| 






|,NSP|NUP|UPD| 






|,KE!2|KGE| 






|,FKS|GEN| 






LNWAITXIVVAITXI 






|,LOC|MVE|)I 






|,RECLEN = numfee/1 






|,TRANSIO -mtmbef] 



SCHBFR (Search BulTcr) 



SCHBFR 



[BFRNO»/iMm6er] 
JUVh- address 
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SIIOWCB (Display Fldds of an Access Method Control Block) 





SHOVVCB 


ACBaddress 




,AREA " address 






.LENGTH -/iMm^r 






[,OBJECT- {DATA|INDEX)I 






,HELDS = (|ACBLEN||,AVSPAC|I,BFRFND| 






i,BSTRNO|I,BtI''NI3||,BUHVIJ 






|3lJFNO||,BUFRDS||,BUFSP| 






(,CINV|f,DDNAMEI|,ENDRBAI 






|,£RRORi|,£XLST)|,FS| 






i,HALCRBAH,KEYLENl|,LRECLl 






IA1AREA||,MLEN|I,NCISI 






|,NDELRI|,NEXCP||,NEXT1 






|,iNINSRl|^IXL||,NLOGR| 






|,NRETRI|,NSSS|I,NUIWI 






|,NUPDR||,PASSVVD||,RKP| 






|^SIIRPOOL|(3TMST|(3TRMAXl 






|;STRNO||,UIW|) 



SHOWCB (Display Mdds of an Exit Lbt) 



{labeH 


SHOVVCB 


AREA = address 






^XLST'^ address 






yLENGlH=- number 






.FIELDS = (|EODADI|,EXLLENII^RNAD| 






|,LERAD||,SYNAD|) 



SHOWCB (Display Fields of a Request Parameter List) 



{!abe/\ 


SHOWCB 


AREA " address 






,LENGTH = /n/m^er 






tRPL'« address 






,nELDS = (|ACB||,AIXPCH,AREA| 






|w\REALENI|,ARGl|,ECBII,FDBK| 






|,FTNCD|I,KEYLENII,MSGAREA| 






|,MSGLEN||,NXTRPL||,RBA| 






|,RECLEN||,RPLLEN|f,TRANSID| 
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TESTCB (Test a Fidd of an 



Access Method Control Block) 



[labeli 


TESTCB 


ACB = address 






lERET'^ address] 






|,OBJECT= DATA|INDEX| 






,{ATRB = (|ESDS||,KSDSII,LDS||,REPL| 






|,RRDS||,SPAN||,SSWD||,WCK|)| 






ATRB-IJNO 






CATALOG = { YESjNO) | 






M ACRE = (IADR||,AIX||,CFX||,CNV|(,DDNI 






|,1)FR||,DIR||,DSN||,GSR|1,ICI| 






|,IN|I,KEY||,I-SR||,NCI||,NDFj 






|,NFX||,NIS||,NRM||,NRS||,NSR| 






|,NUB||,OlJTH,RST||,SEQil,SIS| 






j,SKP||,UBF|)| 






OFLAGS = OPEN| 






OPENOBJ = PATH|BASE|AIX| 






ACBLEN = /ium6er| 






AVSPAC = «w/nM 






hSTRSO^ number] 






BUFNl) = /iumM 






BUFNI = /iwAnM 






BUFNO = number] 






BUFSP = number] 






C\S\^ number] 






DDNAME = </<f/iame| 






ENDRBA = /2wmM 






ERROR = /2wmM 






YXISV = address] 












KEYLEN = numM 






\.VLY.CL = number] 






MXKEX^ address] 






MLEN » number] 






NCIS = number] 






NDELR-/iMm6er| 






NEXCP = /2wm6er| 






NEXT = m/mM 






NINSR«/iMmf>er| 






NIXL " number] 






NLOGR = /i«mM 






NRETR»/iz/wM 






risiSS = number] 






NUPDR ^number] 






VASSWD' address] 






RKP^ number] 






SHRPOOL' number] 






STMST' address] 






STRNO = number] 
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TESTCB (Test a Field of an Exit List) 



[labeli 


TESTCB 


yEXtST=' address 






address] 






,{£ODAD > {0|((a^</rejjlf,Ali\I|,Li)} | 






JRNAD- {0|(|a^/rfrew|I,A|NIJ,LD)| 






LERAD= {0|(Ia£/d>'e5Jl|,A|N|I,L|)}l 






SYNAD= {0|(Iat/</rejjl|,A|N|(,L|)]) 









TESTCB (Test a Field of a Request Parameter List) 



|f UC/C(| 


TFSTrR 


R PI 38 /i/i//nftt 


















AIYFf ACs AlYPKPi 






\^ ~ nwTioer\ 












AREALEN = number\ 






ARG = address\ 






ECB=a£/</rejj| 






FOBK»/zu/nM 






ri'NCD = /?wmM 






KEYLEN = /7wmM 






, MSGXVLEX'-addressi 






MSGLEN -rtMmM 






NXTRI*L = ac/£/rejj| 






IO»COMPLETEI 






OPTCD = (1 ADRII,ARD||,ASYI|,BWD||,CNY| 






I,DIR||,FKS||,F\VI)II,GEN||,KEQ| 






|,KEY||,KGE|I,LOC|I,LRi)||,MVE| 






|,NSP|I,NUP|i,SEQ|I,SKPII,SYN| 






I,IJPDI)| 






RVkX- number] 






RECLEN = /7MmM 






RPLLEN = /zw/nAer| 






TRANSID = rtw/w6er) 



VERIFY (Synchroni/e End of Data) 



\label\ 


VERIFY 


RlfL^ address 






INACTION »REFRESH| 
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WRTBFR (Write BufTcr) 



WRTBFR 



RPL'^ address 

,TYPE-{ALL!CHK|DRBA|DS|LRU(percem)|TRN} 
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ix B. 



List, Execute, and Generate Forms of Macros 



BLDVRP, DLVRP, GENCB. MODCB, SIIOWCB, and TESTCB macros build 
a parameter list describing in codes the actions indicated by the operands you 
specify and pass the list to VSAM to take the indicated action. The list, execute, 
and generate forms of BLDVRP, DLVRP, GENCB, MODCB, SHOVVCB, and 
TESTCB allow you to write reentrant programs, to share parameter lists, and to 
modify a parameter list before using it. 

Following is a brief description of the list, execute, and generate forms: 

• 'Phc list form is used to build the parameter list cither inline (referred to as a 
simple list) or in an area remote from the macro expansion (referred to as a 
remote list). Both the simple- and the remote-list forms allow you to build a 
single parameter list that can be shared. 

• The execute form is used to modify a parameter list and to pass it to VSAM 
for action. 

• Tlic generate form is used to build the parameter list in a remote area and to 
p!Bs it to VSAM fer action. 

The list, execute, and generate forms of the BLDVRP, Dl,VRP, GENCB, 
MODCB, SHOWCB, and TESTCB macros have the same format as the 
standard forms, with the exception of: 

• An additional keyword, MF 

• Keywords that are required in the standard form may be optional in the Ust, 
execute, and generate forms or may not be allowed in the execute form. The 
meaning of the keywords, however, and the notation that may be used to 
cj^ress addresses, names, numbers, and option codes arc the same. 

The sections that follow describe the format of the MF keyword and the use of 
list, execute, and generate forms. They also indicate the optional and invalid 
operands. 
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List-Form Keyword 



The format of the MF keyword for the list form is: 
MF- {L\iL,address[Me^) 

where: 

L 

specifies that this is the list form of the macro. 
address 

specifies the address of a remote area in which the parameter list is to be 
built, llie area must be^n on a fullword boundary. You can specify the 
address in register notation or as an expression valid for a relocatable 
A-type address constant or a direct or indirect S-type address constant. 

label 

is a unique name that is used in an EQU instruction in the expansion of 
the macro; label is equated to the length of the parameter list. You do not 
have to know the length of the parameter list if you code label; the 
expansion of the macro determines the amount of storage required. 

Because the MF= L expansion does not include executable code, register 
notation and expressions that generate S-typc address constants cannot be used. 

If you code MF ~ L, the p^^meter li^ is built inline, which means that the 
program is not reentrant if the parameter list is modified at execution. 

If you code MF==(L,address), the parameter list is built in the remote area 
specified, and the area must be large enough for the parameter list. 

The size, in fullwords, of a parameter list is: 

• For GENCB, 4, plus 3 times the number of ACB, EXLST, or RPL 
keywords specified (plus 1 for DDNAME, EODAD, JRNAD, LERAD, or 
SYNAD) 

• For MODCB, 3, plus 3 times the number of ACB, EXLST, or RPL 
keywords specified (plus 1 for DDNAME, EODAD, JRNAD, LERAD. or 
SYNAD) 

• For SHOWCB, 5, plus 2 times the number of fields specified in the FIELDS 
operand 

• For TESTCB, 8 (plus 1 for either DDNAME. STMST. EODAD, JRNAD, 
LERAD, or SYNAD) 

If you code MF = (L,address,Iabel), the parameter list is built in the remote area 
specified. The expansion of the macro equates label with the length of the 
parameter list. 
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Execute-Form Keyword 

The format of the MF keyword for the execute form is: 
MF " (EiOddress) 

where: 

£ 

specifies that this is the execute form of the macro. 
address 

is the address of the parameter list. 

The expansion of the execute form of the macro results in executable code that 
causes: 

1. A parameter list to be modified if requested 

2. Control to be passed to a routine that satisfies the request 

You may not use the execute form to add an entry to a parameter list. If you try 
to add an entry, you will receive a return code of 8 in re^ster 15. 



Generate-Form Keyword 

The format of the MF keyword for the generate form is: 

MF = (G,address\,iabeA) 

where: 

G 

specifies that this is the generate form of the macro. 
address 

specifics the address of a remote area in which the parameter list is to be 
built, 'llie area must begin on a fullword boundary. 

label 

is a unique name that is used in an EQU instruction in the expansion of 
the macro; label is equated to the length of the parameter list. You do not 
have to know the length of the parameter list if you code label; the 
expansion of the macro determines the amount of storage required. 

If you code MF— (G,address), the parameter list is built in the remote area 
specified. 

If you code MF = (G,address,label), the parameter list is built in the remote area 
specified. The expansion of the macro equates the length of the parameter list to 
label. 
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I List, Execute and Generate Formats 



List Form of BLDVRP 

Note: If FIX is specified, DLVRP must be issued by the same task that issues 
BLDVRP. STRNOisoptionalinthclistformof BLDVRP, but, ifitisnot 
specified, it must be specified in the execute form. 

The format of the list form of BLDVRP is: 



BLDVRP 


BUFFERS = (size{number),size{number)j,,.) 




,MF=L 




I,FIX {BFR|IOBi(BFR,IOB»i 




I,KEVLEN = /e/i^/AJ 




I.RMODE3t = f ALLIBUFFICBINONEll 




|,SIIRPOOL»(0|n}| 




|,MODE = {24131)1 




ISTRSO^ number] 




I.TYPE » I LSRI.D ATA 1 INDEXIiGSR) 1 



Execute Form of BLDVRP 

Note: The address is the address of the parameter list built by a list form of 
BLDVRP. If you use register notation, you may use register 1, and a register 
betweerr 2and 12. Register t is used fb pass the parameter Gst to VSAM. 
BUFFFRS may not be specified in ♦he execute form of BLDVRP, because this 
operand alTccts the length of the parameter list. 

The format of the execute form of BLDVRP is: 



BLDVRP 


MF = (E,arf</rew) 




|,KEVLEN»/e/i^//i| 




f.RMODE31 = fALLIBUFFICBINONFJl 




i,SHRPOOL »/n/mM 




|;V10DE»{24|3]}| 




ISlKSO^numberl 




I. TYPE - fLSRI.DATAIIM)EXIICSRn 



I Note: If MODE » 3 1 was specified on the list form, MODE - 3 1 must be 

t specified on the execute form. The same is true for MODE ~ 24. 



174 MVS/XA \^AM Administradofi: Macro Instruction Reference 



Execute Form of DLVRP 



Note: There is no list forni for DLVRP, because DLVRP works with 
BLDVRP: It uses the parameter list associated with BLDVRP. The address is 
the address of the parameter list built by a list form of BLDVRP. If you use 
register notation, use register 1 to pass the address of the parameter list to 
VSAM. 

If MODE = 31 in the BLDVRP macro, then MODE = 31 is required in the 
DLVRP macro. 

The format of the execute form of DLVRP is: 



DLVRP 


MF = (EfOddress) 




|,SHRPOOL«/ii/m6e/i 




|,MODE={24|3l)I 




,TVPE«{I-SR|GSR} 



UstFormofGENCB 

llic format of the list form of GENCB is: 



[labeli 


GENCB 


BLK= {ACB|EXLST|RPL} 






I.AM = VSAM1 






|,COPIES«/iMm^efI 






[keyword - {address\name\numb€r\option]f..,\ 






I,LENGTH = m/m6c/i 






I.LOC=fBELOW|ANY)l 






LRMODE3I = I ALLlBUmCBlNONE)! 






,MF = {L\(Uaddress\Jabeii)] 






l\\ AREA'' address] 



Execute Fonri of GENCB 

The format of the execute form of GENCB is: 



\labeli 


GENCB 


BLK= {ACB|EXLST|RPL) 






I.AM = VSAM1 






|,COPlES = /ium6ei 






[Jceyword = {address\name\number\option) ,...| 






|,LENGTH-/itim6er| 






IXOC=fBELOW|ANY)l 






KRMODE31 « ( ALLiBUFt ICBiNONEll 






,MF - (E^dress) 






IW AREA-' addres^ 
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Generate Fonn of GENCB 



The format of the generate form of the GENCB macro is: 



{labeli 


GENCB 


BLK» (ACBIEXLSTiRPL) 






|.AM = VSAMr 






ICOPIES^ number] 






[keyword - address\n<une\number\option] ,...) 






I,LENGTH = m<m6er| 






IXOC= fBELOVVIANY)! 






l,RMODE3l - (ALLIBUFFICBINONEII 






,MF = (G,ac/i/rejj|,/a6e/|) 






|,WAREA = a<frfrew| 



List Form of MODCB 

The format of the list form of MODCB is: 



\lahel\ 


iMODCB 


{ ACB|EXLST|RPL{ = a</c/rejj 






Jceyword - [address\name\numher\option],... 






,iMF= {L\{Uaddress\Jabel\)} 



Execute Form of \I()I)CB 

Note: If the executafornLof MODCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB = . 

The format of the execute form of MODCB is: 



\label\ 


MODCB 


|{ACB|EXLST|RPL) = address] 






keyword = {address\name\number\option}t... 






,MF=(E,<K/d>'ew) 



Generate Form of MODCB 



The format of the generate form of MODCB is: 



[labeli 


MODCB 


{ACB|EXm |RPL{ - address 






fkeyword - [address\nanie\number\option},,,. 






,MF = (G,<i£Wr^ j4,/aM) 
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UstFormofSHOWCB 

The format of the list form of SHOWCB is: 



[labeli 


SHOWCB 


|(ACB|EXLST|RPL) = address] 






,AREA = address 






,FIFXDS = (keyword{^eywordf..JI^ 






,I-ENGTH = number 






,MF = {L\{Uaddress[JabeH)] 






,ORIECT= fDATAIINDEXll 



Execute Form of SHOWCB 

llie format of the execute form of SHOWCB is: 



\label\ 


SHOWCB 


\[ACn\EXlST\RPL]'^ address 






,AREA = address 






,MF " {E,address) 






KOBJECT" {DATAIINDEXir 



Generate Form of SHOWCB 



The format of the generate form of SHOWCB is: 



\label[ 


SHOWCB 


I{ACB|EXm IRPL} = address] 






,AREA = address 






^FIELDS = (keyword[,keyword,...\) 






XV:S(nn^ number 






,MF = iG,addresslIabeI\) 






|,OIUECT= (DA TAIINDFZXll 



List Form of TESTCB 

Note: If the execute form of TESTCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB = . 

The format of the list form of I'ESTCB is: 



[label] 


lESICB 


|{ACB|F:XLST|RPL) = address] 






lERET^ address] 






keyword = {address\name\mtmber\option)^„. 






,MF= [E\{E,addres^\Me^)) 






l,OBJECT= fDATAIINDEXll 
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Execute Form of TESTCB 

Note: If the execute form of TESTCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB = . 

The format of the execute form of TESTCB is: 



\lab€l\ 


TESTCB 


|{ACB|EXI^T|RI»L] =a</</r€wI 












keyword - [address\name\number\option]j,„ 






,MF = {EfOddress) 






I.ORIECT= fDATAIINDEXll 



Generate Form of I'ES TCB 



The format of the generate form of TESTCB is: 



\label\ 


Ti:STCB 


|{ACB|EXLST|RPL) = address\ 






lER¥:r = address] 






keyword = {address\name\nwnher\option] 






MV = {G,addressyabel[) 






r.OBJECT= fDATAIINDEXII 



Use of List, Execute, and Generate Forms 

Figure 16 indicates which forms of GENCB, MODCB, SHOWCB, and 
TESTCB should be used in rccntrant/nonreentrant and shared/nonsharcd 
environments. 



Reentrant 

Shared M¥ = {Uaddres^Jabel^ 

MF ^iE,address) 

Nonshared MF - {G,addres^,labeij) 
Figure 16. Reentrant Programming 



The figure shows that: 

• To share parameter lists in a reentrant program, the remote-list form should 
be used in conjunction with the execute form. 

• To share parameter lists in a nonreentrant program, the simple-list form 
should be used in conjunction with the execute form. 
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Nonreentrant 

MF=L 

MF ^ {E,address) 
Standard Form 



• If you do not intend to share parameter lists, the generate form should be 
used in reentrant programs and the standard form should be used for 
nonrecntrant programs. 



Examples of Generate, List, and Execute Forms in Reentrant Environments 

The examples that follow illustrate how the list, execute, and generate forms 
work. 

Example: Generate Form (Reentrant) 

In this example, the generate form of GENCB is used to create a default request 
parameter list (RPL) in a reentrant environment. 

LA 10,LEN1 Get length of the parameter list. 

GETMAIN R,LV-(10) Get storage for the area in which 

the parameter list is to be built. 

LR 2,1 Save address of parameter- list 

area. 

GENCB BLK=RPL, 

MF=(G,(2),LEN1) 

llie macro expansion equates LENl to the length of the parameter list, as 
follows: 

+LEN1 EQU 16 

The parameter list will be built in the area acquired by the GBTMAIN macro 
■and pointed to by register 2. This fist t& used hy VSAM to ha^d ll» RPL. 
VSAlVi returns the RPL address in re^ster 1 and the RPL length in rc^stcr 0. If 
the WAREA and LENGTH parameters are used, the RPL will be built at the 
VVAREA address. 

Example: Remote-List Form (Reentrant) 

In this example, the remote-list form of MODCB is used to build a parameter list 
that wUl later be used to modify the MACRF bits in the access method control 
block ANYACB. 

LA 8,LEN2 Get length of the parameter 

list. . 

GETMAIN R,LV=(8) Get storage for the area in 

which the parameter list is to 
be built. 

LR 3,1 Save address of the 

parameter -list area. 

MODCB ACB=ANYACB, 

MACRMF=(L,(3),LEN2) 

The macro expansion equates the length of the parameter list to LEN2, as 
follows: 

+LEN2 EQU 24 
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This parameter list is built in the remote area pointed to by register 3. The list 
will be used by VSAM to modify the ACB when an execute form of MODCB is 
issued (see next example). The list form only creates a parameter list; it does not 
modify the ACB. 

Example: Execute Fomi (Reentrant) 

In this example, the execute form of MODCB is used to modify the address of 
the access method control block and MAC RF codes in the parameter list created 
by the remote-list form of MODCB in the previous example. 

MODCB ACB=MYACB , MACRF=( ADR, SEQ, OUT) , MF=(E , ( 3) ) 

The parameter list pointed to by register 3 is changed so that the ACB and 
MACRF parameter values in the execute form override those in the list form. 
The access method control block, MYACB, is then modified to 
MACRF = ADR,SEQ.OUT). The access method control block at ANYACB is 
not changed by either of these examples. 
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Appendix C. Operand Notation 



Operands with GENCB, MODCB, SHOWCB, and TESTCB 

The addresses, names, numbers, and options required with operands in GENCB, 
MODCB, SIIOWCB, and TESTCB can be expressed in a variety of ways: 

• An absolute numeric expression, for example, STRNO = 3 and COPIES = 10. 

• A code or a list of codes separated by commas and enclosed in parentheses, for 
example, OPTCD= KEY or OPTCD = (KEY.DIR.IN). 

• A character string, for example, DDNAMIi= DATASin\ 

• A register from 2 through 12 that contains an address or numeric value, for 
example, SYNAD = (3); equated labels can be used to designate a register, for 
example, SYNAD = (ERR), where the following equate statement has been 
included in the program: ERR EQU 3. 

• An expression of the form (S,scon), where scon is an expression valid for an 
S-typc address constant, including the base-displacement form. The contents 
of the base register will be added to the displacement to obtain the value of 
the keyword. For example, if the value of the ke>'word being represented is a 
numeric value (that is, COPIES, LENGTH, RECLEN), the contents of the 
base register will be added to the displacement to determine the numeric 
value. If the value of the keyword being represented is an address constant 
(that is, WAREA, EXLST, EODAD, ACB), the contents of the base register 
will be added to the displacement to determine the value of the address 
constant. 

• An expression of the form (*vscon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form; the address 
specified by scon is indirect, that is, it is the address of an area that contains 
the value of the keyword. The contents of the base re^stcr will be added to 
the -displacement to determine the address of the fuUword of storage that 
contains the value of the keyword. 

If an indirect S-type address constant is used, the value it points to must meet 
the following criteria: 

— If it is a numeric quantity or an address, it must occupy a fullword of 
storage. 
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— If it is an alphameric character string, it must occupy two words of 
storage, be left aligned, and be filled on the right with blanks. 

• An expression valid for a relocatable A-t>pe address constant, for example, 
AREA«MYAREA+4. 

The specified keyword determines the type of expressions that can be used. 
Additionally, register and S-type address constants cannot be used when MF- L 
is specified. 



The tables containing the individual macro operand notations have been deleted 
from this release. Thb information may be obtained from the individual macro 
descriptions shown In Chapter 2, *'VSAM Macro Formats and Examples". 
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Appendix D. Building Parameter Lists 



The standard foiros of GENCB, MODCB, SHOWCB, and TESTCB build a 
parameter list, put its address in register 1, and pass control to a VSAM routine 
to generate, modify, display, or test an access method control block, exit list, or 
request parameter list. Other forms of the macros only build the parameter list 
(list forms) or only pass control to VSAM (execute forms). 

You can avoid using a macro to build the parameter list by building it yourself 
and issuing the execute form of the macro to pass control to VSAM. This 
chapter explains how to build the parameter lists for GENCB, MODCB, 
SHOWCB, and TESTCB. ITie rules for combinations of codes in a parameter 
list are the same as the rules for combinations of operands in a macro. 

You can avoid issuing the execute form of the macro by coding the linkage 
instructions that pass control directly to the VSAM control block manipulation 
routine. Before passing control, you must build the parameter list yourself. 



The Format of the Parameter Lists 

A parameter list for GENCB, MODCB, SHOWCB. or TESTCB is a list of 
fullword addresses. The first address points to a header entry that identifies the 
type of request and type of control block and gives other general information 
about the request. Each of the rest of the addresses in the parameter list points 
to an element entry that identifies the information you want to generate, modify, 
display, or test. 

The fuUwords in the parameter list must be contiguous, and the last one must 
have a 1 in its first bit. llie header entry and each clement entry may be separate 
from each other. Figure 17 on page 184 ^ves the formats of the header and 
element entries for the four request types. 
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Generation 
GENCB 



Header Entry 



Element Entiy 



GENBTC 


GENFTC 




GENCOP 


0 


ELEMKWTC 


(reserved) 


Control- 
block type 


Function 
type 


Number of copies 
of block 




Keyword 
type 




GENUSA (optional) 

Address of area provided 
for generation 


4 


Keyword value 


GENUSL (optional) 
Length of area 


(reserved) 




(required for 
1 some keywords)* 


1 
1 

















Modification 
MODCB 



0 


MODBTC 


MODFTC 


(reserved) 


0 


ELEMKWTC 


(reserved) 




Control- 


Function 






Keyword 






block type 


type 






type 




4 


MODBLAD 




4 






Address of control block 




Keyword value 




to be modified 







(required for 
I some keywords)* 



Display 
SHOWCB 



0 


SHOWBTC 


SHOWFTC 


SHOWOBJ 




(optional) 
Control- 


Function 


Object type 




block type 


type 




(data or index) 


4 


SHOWBtAD (optional) 








Address of control 






8 


block to be displayed 






SHOWUSA 










Address of area provided 




12 


for display 








SHOWUSL 




(reserved) 




Length of area 







ELEMKWTC 


(reserved) 


Keyword 




type 





Test 

TESTCB 



12 



TESTBTC 


TESTFTC 


TESTOBJ 


(optional) 
Control- 


Function 


Object type 


block type 


type 


(data or index) 


TESTBLAD (optional) 




Address of control 




block to be tested 




TESTERET (optional) 




Address of error-analysis 




routine (ERET) 




(reserved) 



ELEMKWTC 


(reserved) 


Keyword 




type 




Keyword value 


(required for 


1 


1 some keywords)* 


[ 



*Second fuilword required for 
keyword value of DDNAME, 
STMST, EODAD, JRNAD. 
LERAD. and SYNAD. 



Figure 17. Format of Header and Element Entries for GENCB, MODCB, SHOWCB, and TESTCB Parameter Lists 
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Building Header and Element Entries 



Five assembler macros are provided for building entries. 
IDAGENC, IDAMODC, IDASHOW, and IDATEST help you build a header 
entry for generation, modification, display, or test. IDAELEM helps you build 
an element entry. 



\lahel\ 


IDAGENC 


|DSECT={YES|\0]| 


\/abe/{ 


IDA.MODC 


|DSECT={YES|NO)| 


\lab€l\ 


IDASHOW 


IDSECT={YES|XO]| 


\Iabel\ 


IDATEST 


|DSECT=fYESINOn 


\label[ 


IDAELEM 


|DSECT={YI^|NO]I 



DSECT={YES|NO} 

Indicates whether a DSECT statement is to be generated. If you intend to 
build entries in a continuous area, you could have only the first of the 
macros generate a DSECT statement and use a single register to address the 
whole area. 

lliese macros generate labeled DS statements that give the layout of an cntr>' and 
EQU statements that equate a label with a numeric code. You can symbolically 
encode an entry with a series of move instructions. The macros are 
self-documenting— inspect a listing of their expansions and you can see which 
labels to code in your move instructions. (You can list the macros as they 
appear in the macro library.) 

To generate an exit list with LEkAD and SYNAD exits, you could code a 
GENCB of the standard form: 

GENCB BLK=EXLST, LERAD=CLOGERR, L) , SYNAD=PHYSERR 

The following example shows how to achieve the same effect by building the 
parameter list and entries yourself and issuing a GENCB of the execute form. 



Build the list of addresses that point to the entries. 



LA 



5,NTRYAREA 



Set up base register for 
the entries. 



USING 5,GENC 



GENC is the first label in 
the work area. 



ST 



5,PLIST 



Address of the header 
entry. 



LA 



6,GENLEN(,5) 



Address of the first 
element entry. GENLEN is 
equated to the length of 
a header element for 
generation. 



ST 



6,PLIST+4 



Appendix D. Building Parameter Lists 185 



LA 6,£L£MLLEN(,6) 



ST 6,PLIST+8 
01 PLIST+8,X*80* 
Build the header entry. 

MVI 6ENBTC,6ENXLST 

MVI GENFTC.GENFTYP 

MVI GENCOP+l.X'Ol* 



MVI ELEMKWTC+1, 
ELEMLEAO 

LA 6,L0GERR 



ST 6,ELEMPTR 

MVI ELEMXFL6, 

ELEMXLcfeELRMXADR 



Build the second element entry. 



Address o£ the second 
element entry. ELEMLLEN 
is equated to the length 
of an element entry for 
an exit list. 



End-of -list indicator. 



Indicate the 
blocktype-exit list. 

Indicate the function 
t ype *• gener at ion . 

Indicate the number of 
copies of the exit list 
to be generated. 

Indicate the keyword type- 
LERAD. 

Address of the name of the 
logical error analysis 
module. 



Indicate the presence of 
an. address EL£M£TR and 
that the exit routine is 
to be loaded. 



LA 



MVI 
LA 

ST 
MVI 



5,ELEMLLEN(,5) 



ELEMKWTC+1, 
ELEMSYAD 



6,PHYSERR 



6,ELEMPTR 

ELEMXFLG, 
ELEMXADR 



Align the DSECT with the 
second element entry. 
ELEMLLEN is equated to the 
length of an element entry 
for an exit list. 

Indicate the keyword 
type-SYNAD. 

Address of the entry point 
of the physical error 
analysis routine. 



Indicate the presence of 
an address in ELEMPTR. 



Pass control to VSAM. 

GENCB MF=(E,PLIST) 
LTR 15,15 
BNZ CHECKO 



Generation successful? 
No. 
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CHECKO ABEND 1,DUMP 



Register 0 indicates the 
error. 



Physical error analysis exit routine. 
PHYSERR . . . 



Work areas and constants. 
L06ERR DC CL8*LEM0D' 

PLIST DC 3F'0* 
NTRYAREA DC 9r*0* 



Name of the 

logical error analysis 

module to be loaded. 

List of entry addresses. 
3 addresses are 
required: 1 for the header 
and 2 for the elements 
(1 for LERAD and 1 for 
SYNAD). 

Work area for header and 
element entries. The 
header for GENCB is 3 
fullwords, and so are 
the LERAD and SYNAD 
elements. 



DSECT with labels for the header and element entries. 

IDAGENC Header entry. A DSECT 

statement is generated, 
and register 5 is used 
to address NTRYAREA 
with these labels. 

IDAELEM DSECT=NO Element entry. Element 

labels are part of the 
same DSECT as the 
header labels. 



Passing Control Directly to VSAM 

You can avoid using the execute form of GENCB, MODCB, SHOWCB, and 
TESl'CB by building your own linkage instructions. You first build a parameter 
list, as described in the previous section, and put its address in register 1. Then 
you pass control to VSAM using the following instructions: 

L 15,16 Put the address of the CVT 

into register 15. 

L 15,256(,15) Put the address of the AMCBS 

control block into register 15. 

L 15,12(,15) Put the address of the control 

block manipulation routine into 
register 15. 

BALR 14,15 Branch to the routine 

The BALR 14,15 instruction is used when the specific function (GENCB, 
MODCB. SHOWCB, or TESTCB) is not known, or when the control block 
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type (ACB, EXLST, or RPL) is not known. The user-built parameter list 
contains the function code and control block type code. 



Decimal 






Value of XX 


Function 


Control Block 


8 


GENCB 


ACB 


12 


GENCB 


RPL 


16 


GENGB 


EXLST 


20 


Reserved 




24 


MODCB 


ACB 


28 


MODCB 


RPL 


32 


MODCB 


EXLST 


36 


Reserved 




40 


snowcB 


ACB 


44 


SIIOWCB 


RPL 


48 


SIIOWCB 


EXLST 


52 


Reserved 




56 


TESTCB 


ACB 


60 


TESTCB 


RPL 


64 


TESTCB 


EXLST 


68 


Reserved 




72 


SIIOWCB or 


Block length 




FESrCB 


keywords only 


76« 


SIIOWCB 


RECLEN field 






of an RPL 


80> 


MODCB 


RECLEN field 






of an RPL 



• Re^ster 1 points to an RPL when xx is 76 or 80. Sec the following section 
for details. 

When VSAM returns to your program, register 15 contains a completion code. 
Register 15 contains a zero value if the task completed successfully. Otherwise, 
register 15 and register 0 contain codes that identify the reason VSAM could not 
complete the task. 

Modifying and Displaying the RECLEN Field of an RPL Directly 

You can modify or display the RECLEN field (that is, the record length) of an 
RPL without issuing a SIIOWCB or MODCB macro, and without building a 
parameter list. 

To modify a RPL's RECLEN field, you first put the address of the RPL in 
register 1, and the value to be set in the RECLEN field in register 0. Next, you 
code the instructions that put the address of the VSAM control block 
manipulation routine into register 15, then branch to the routine: 
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L 15,16 Put the address of the CVT into 

register 15. 

L 15,256(,15) Put the address of the AMCBS 

control block into register 15. 

L 15,12(,15) Put the address of the control 

block manipulation routine 
into register 15. 

BAL 14,80(,15) Branch to the routine. 

When VSAM returns to your program, register 15 contains a completion code. 
Register 15 contains a zero value if the field was modified correctly. Otherwise, 
rc^ster 1 5 and register 0 contain codes that identify the reason VSAM could not 
complete the task. 

To display the contents of a RPL's RHCLEN field, you first put the address of 
the RPL in register 1. Next, you code the instructions that put the address of the 
VSAM control block manipulation routine into register 15, and then branch to 
the routine: 

L 15,16 Put the address of the CVT into 

register 15. 

L 15,256(,15) Put the address of the AMCBS 

control block into register 15. 

L 15, 12 (,15) Put the address of the control 

block manipulation routine into 
register 15. 

BAL 14,76(,15) Branch to the routine. 

When VSAM returns to your program, rc^stcr 15 contains a completion code. 
Register 15 contains a zero value if the field is displayed correctly, and register 0 
contains the value of the RPL's RECLHN field. When register 15 is not zero, 
register 15 and register 0 contain codes that identify the reason VSAM could not 
complete the task. 
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Glossary of Terms and Abbreviations 



The following terms arc defined as fhcy are used in this 
book. If you do not find the term you are looking for, 
see the index or the IBM Vocabulary for Data 
Processing, Telecommunications, and Office Systems, 
GC20-1699. 

ACB. (See access method control block.) 

access method control block. A control block that links 
an application program to VSAM or ACF/VTAM. 

access method services. A multifunction service 
program that is used to define VSAM data sets and 
allocate space for them, convert indcxcd-scquential data 
sets to key-scqucnccd data sets, modify data set 
attributes in the catalog, reorganize data sets, facilitate 
data portability between operating systems, create 
backup copies of data sets, help make inaccessible data 
sets accessible, list the records of data sets and catalogs, 
define and build alternate indexes, and convert OS 
CVOLs and VSAM catalogs to integrated catalog 
factltly catalogs. 

acquire. To allocate space on a staging drive and to 
stage data from an MSS cartridge to the staging drive. 

addressed-direct access. The reUieval or storage of a 
data record identified by its RBA, independent of the 
record's location relative to the previously retrieved or 
stored record. (/See also keyed-direct access, addressed- 
sequential access, and keyed-sequential access.) 

addressed-sequential address. The retrieval or storage of 
a data record in its entry sequence rdative to the 
previously retrieved or stored record. (See also 
keyed-sequential access, addressed-direct access, and 
keyed -direct access.) 

alternate index. A collection of index entries organized 
by the alternate keys of its associated base data records. 
It provides an alternate means of locating records in the 
data component of a duster on whidi the alternate 
index is based. 

alternate index cluster. The data and index components 
of an alternate index. 

alternate key. One or more consecutive characters 
taken from a data record and used to build an alternate 



index or to locate one or more base data records' via an 
alternate index. (See also generic key, key, and key 
field.) 

APF. (See authorized program facility.) 

application. As used in this publication, the use to 
which an access method is put or the end result that it 
serves: contrasted to the internal operation of the access 
method. 

authorized program facility. A facility tlial permits the 
identification of programs that arc authorized to use 
restricted functions. 

ba.sc cluster. A key-scqucnced or entry-sequcnccd data 
set over which one or more alternate indexes are builL 

base RBA. The RBA stored in the header of an index 
record that is used to calculate the RB As of data or 
index control intervals governed by the index record. 

catalog. (See master catalog and user catalog.) 

catalog recovery area. An cntry-scqucnced file that 
exists on each volume owned by a recoverable catalog, 
including the catalog itself. The CRA contains records 
that are duplicates of the catalog entries describing the 
volume and the files it contains. 

CBIC. Control blocks in common, a facility that allows 
a user to open a VSAM data set so the VSAM control 
blocks arc placed in the common service area (CSA) of 
the MVS operating system, lliis provides the capability 
for multiple memory accesses to a single VSAM control 
structure for the same VSAM data set 

chained RPL. (See RPL string.) 

CI. (See control interval.) 

CIDF. (See control interval definition field.) 

cluster. A named struOure consisting of a group of 
related components (for example, a data component 
^th its index component). A cluster may consist of a 
single component (See also base cluster and alternate 
index cluster.) 
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collating sequence. An ordering assigned to a set of 
items, such that any two sets in that assigned order can 
be collated. 

component. A named, cataloged collection of stored 
records. A component, the lowest member of the 
hierarchy of data structures that can be cataloged* 
contains no named subsets. 

control area. A group of control intervals used as a unit 
for formatting a data set before adding records to it 
Also, in a key-sequenced data set, the set of control 
intervals pointed to by a sequence-set index record; used 
by VSAM for distributing free space and for placing a 
sequence-set index record adjacent to its data. 

control area split. The movement of the contents of 
some of the control intervals in a control area to a 
newly created control area, to facilitate the insertion or 
lengthening of a data record when there are no 
remaining free control intervals in the original control 
area. 

control interval. A fixed-length area of auxiliary storage 
space in which VSAM stores records. It is the unit of 
information transmitted to or from auxiliary storage by 
VSAM. 

control interval access^ llie retrieval or storage of the 
eontcats of arContcol intecval. 

control interval definition field. In VSAM, the 4-byte 
control information field at the end of a control interval 
that gives the displacement from the beginning of the 
controi interval to free space and the length of the free 
space. If the length is 0, the displacement is to the 
beginning of the control information. 

control interval split. The movement of some of the 
stored records in a control interval to a free control 
interval, to facilitate the insertion or lengthening of a 
record that won't fit in the original control interval. 

control volume. A volume that contains one or more 
indexes of the catalog. 

CKA. (5ee catalog recovery area.) 

cross memory. A synchronous method of 
communication between address spaces. 

CVOL. {See control volume.) 

DASD. {See direct access storage device.) 

data record. A collection of items of information from 
the standpoint of its use in an application, as a user 
supplies it to VSAM for storage. 



data set. The major unit of data storage and retrieval 
in the operating system, consisting of data in a 
prescribed arrangement and described by control 
information to which the system has access. As used in 
this publication, a collection of fixed- or variable-length 
records in auxiliary storage, arranged by VSAM in 
sequence or in entry sequence. {See also key-sequenced 
data set and entry-sequenced data set) 

DO statement, data definition statement 

direct access. The retrieval or storage of data by a 
reference to its location in a data set rather than relative 
to the previously retrieved or stored data. {See also 
addressed-direct access and keyed-direct access.) 

direct access storage device. A device in which the 
access time b cficctively independent of the location of 
the data. 

EBDIC Extended binary-coded decimal interchange 
code. A coded character set consisting of 8 -bit coded 
characters. 

entry sequence. The order in which data records are 
physically arranged (according to ascending RBA) in 
auxiliary storage, without respect to their contents. 
(Contrast with key sequence.) 

entry-sci^uenccd data set. A data set whose records are 
loaded without respect to their contents, and whose 
RBAs cannot change. Records are retrieved and stored 
by addressed access, and new records are added at the 
end of the data set 

EOD. end of data 

EOKR. end-of-key range 

EOV. end of volume 

field. In a record or a control block, a specified area 
used for a particular category of data or control 
information. 

free control interval pointer list. In a sequence-set index 
record, a vertical pointer that gives the location of a free 
control interval in the control area governed by the 
record. 

free space. Space reserved within the control intervals 
of a key-sequenced data set for inserting new records 
into the data set in key sequence; also, whole control 
intervals reserved in a control area for the same 
purpose. 

GENDSP. An option of LOCATE to obtain tiic 
control interval number of the catalog record of each 
object 
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generation data group. A collection of data sets that are 
kept in chronological order; each data set is called a 
generation data set. 

generic key. A high-order portion of a key, containing 
characters that identify those records that are significant 
for a certain application. For example, it might be 
desirable to retrievie all records whose keys begin with 
the generic key AB, regardless of the full key values. 

global shared resources. An option for sharing I/O 
buffers, I/O-rclatcd control blocks, and channel 
programs among VSAM data sets in a resource pool 
that serves all address spaces in the system. 

GSK. {See global shared resources.) 

t header, index record. In an index record, the 24-byte 
field at the beginning of the record that contains control 
information about the record. 

header entry. In a parameter list of GENCB, MODCB, 
SIIOVVCB, or TFSTCB, the entry that idcnUfics the type 
of request and control block and gives other general 
information about the request. 

' horizontal pointer. In the header of an index record, the 
RBA of the index record in the same level as this one 
that contains keys next in ascending sequence after the 
keys in this one. 

index. As used in this publication, an ordered collection 
of pairs, each consisting of a key and a pointer, used by 
VSAM sequence and locate the -records of a 
key-sequenced data set. 

index level. A set of index records that order and give 
the location of all the control intervals in the next lower 
level or in the data set that it controls. 

index record. A collection of index ratries that are 
retrieved and stored as a group. (Contrast to data 
record.) 

index record header. In an index record, the 24-byte 
field at the beginning of the record that contains control 
information about the record. 

index replication. The use of an entire trade of direct 

access storage to contain as many copies of a single 
index record as possible; reduces rotational delay. 

index set. The set of index levels above the sequence 
set. 'Ilie index set and the sequence set together 
comprise the index. 

integrated catalog facility. The name of the catalog 
associated with the Data Facility Product program 
product 



lOPID. I/O prevention identifier which is used to 
terminate I/O and prevent new I/O from being started. 

ISAM, indexed sequential access method 

ISAM interface. A set of routines that allow a 
processing program coded to use ISAM Cmdexed 
sequential access method) to gain access to a 
key-sequenced data set. 

JCL. {See job control language.) 

job catalog. A catalog made available for a job by 
means of the JOBCAT DD statement. 

job control language. A problem -oriented language 
designed to express statements in a job that are used to 
identify the job or describe its requirements to an 
operating system. 

job step catalog. A catalog made available for a job by 
means of the SIT.PCAT DD statement 

key. One or more characters within an item of data 
that arc used to identify it or control its use. As used in 
this publication, one or more consecutive characters 
taken from a data record, used to identify the record 
and establish its order with respect to other records. 
(See also key field and generic key.) 

key field. A field located in the same position in each 
record of a data set whose contents are used for the key 
of a record. 

key sequence. The collating sequence of data records, 
determined by the value of the key field in each of the 
data records. May be the same as, or different from, 
the entry sequence of the records. 

key-sequenced data set. A VSAM file (data set) whose 
records are loaded in key sequence and controlled by an 
index. Records are retrieved and stored by k^ed access 
or by addressed access, and new records are inserted in 
key sequence by means of distributed free space. 
Relative byte addresses of records can change because 
of control interval or control area splits. 

keyed-direct access. The retrieval or storage of a data 
record by use of cither an index that relates the record's 
key to its relative location in the data set or a relative 
record number, independent oi the record's location 
relative to the previously retrieved or stored record. 
(See also addressed-direct access, keyed-sequential 
access, and addressed-sequential access.) ^ 

keyed-sequential access. The retrieval ohfitorage of a 
data record in its key or rdative record sequence relative 
to the prc\^ously retrieved or stored record, as defined 
by the sequence set of an index. (See also 
addressed-sequential access, keyed-direct access, and 
addressed-direct access.) 
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level number. For the index of a key-scquenced data 
set, a binary number in the header of an index record 
that indicates the index level to which the record 
belongs. 

I linear data set (LDS). A named linear string of data, 
I stored in such a way that it can be retrieved or updated 
I in 4096 byte units. An LDS object is essentially a 
I VSAM entry -sequenced data set that is processed as a 
I control interval, i lowcvcr, unlike a control interval, an 
I LDS contains data only, that is, it contains no record 
I definition fields (RDFs) or control interval definition 
( fields (CI DFs). 

local shared resources. An option for sharing I/O 
buffers, l/O-related control blocks, and channel 
programs among VSAM data sets in a resource pool 
that serves one partition or address space. 

I LDS. (See linear data set) 

LSR. {See local shared resources.) 

master catalog. A catalog that contains extensive data 
set and volume information that VSAM requires to 
locate data sets, to allocate and deallocate storage space, 
to verify the authorization of a program or operator to 
gain access to a data set, and to accumulate usage 
statistics for data sets. 

operating system. Software that controls the execution 
of programs; an operating system may provide services 
such as resource allocation, scheduling, input/output 
control, and data management. 

password. A unique string of characters stored in a 
catalog that a program, a computer operator, or a 
terminal user must supply to meet security requirements 
before a program gains access to a data set. 

path. A named, logical cntiQr composed of one or more 
clusters (an alternate index and its base cluster, for 
example). 

physical record. A physical unit or recording on a 
medium. For example, the physical unit between 
address markers on a disk. 

pointer. An address or other indication of location. 
For example, an RBA is a pointer that gives the relative 
location of a data record or a control interval in the 
data set to which it belongs. 

prime index. The index component of a key-sequcnced 
data set that has one or more alternate indexes. (See 
also index and alternate index.) 

prime key. {See key. y 

QSAM. {See queued sequential access method.) 



queued sequential access method. An extended version 
of the basic sequential access method (BSAM). When 
this method is used, a queue is formed of input data 
blocks that are awaiting processing or output data 
blocks that have been processed and are awaiting 
transfer to auxiliary storage or to an output device. 

RACF. Resource Access Control Facility. 

random access. {See direct access.) 

RBA. Relative byte address. The displacement 
(expressed as a fullword binary integer) of a data record 
or a control interval from the beginning of the data set 
to which it belongs; independent of the manner in which 
the data set is stored. 

RDF. {See record definition field.) 

record. {See index record, data record.) 

record definition field. A field stored as part of a stored 
record segment; it contains the control information 
required to manage stored record segments within a 
control interval. 

relative byte address. {See RBA.) 

relative record data set. A data set whose records are 
loaded into fixcd-fength slots. 

relative record number. A number that identifies not 
only the slot, or data space, in a relative record data set 
but also the record occupying the slot. Used as the key 
for keyed access to a relative record data set. 

replication. {See index replication.) 

request parameter list. A control block that contains 
the information needed to process an I,0 request 

resource pool, VSAM. {See VSAM resource pool.) 

reusable data set. A VSAM data set that can be reused 
as a work file, regardless of its old contents. Must not 
be a base cluster. 

RI'L. {See request parameter list.) 

RPi^ string. A set of chained RPLs (the set may 
contain one or more RPLs) used to gain access to a 
VSAM data set by action macros (GET, PU T, etc). 
Two or more RPL strings may be used for concurrent 
direct or sequential requests made from a processing 
program or its subtasks. 

SAM. (5ee sequential access method.) 

security. {See data security.) 
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sequence checking. The process of verifying the order 
of a set of records relative to some field's collating 
sequence. 

sequence set. The lowest level of the index of a 
key-sequenced data set; it gives the locations of the 
control intervals in the data set and orders them by the 
key sequence of the data records they contain. The 
sequence set and the index set together comprise the 
index. 

sequential access. The retrieval or storage of a data 
record in either its entry sequence, its key sequence, or 
its relative record number sequence, relative to the 
previously retrieved or stored record. (See also 
addressed -sequential access and keyed-sequential 
access.) 

sequential access method. An access method for storing 
or retrieving data blocks in a continuous sequence, using 
cither a sequential access or a direct access device. 

shared resources. A set of functions that permit the 
sharing of a pool of l/O-relatcd control blocks, channel 
programs, and buffers among several VSAM data sets 
open at the same time. 

skip-sequential access. Keyed-sequential retrieval or 
storage of records here and there throughout a data set, 
skipping automatically to the desired record or collating 
position for insertion: VSAM scans the sequence set to 
find a record or a collating position. Valid for 
processing in ascending sequences only. 

slot. For a relative record data set, the data area 
addressed by a relative record number which may 
contain a record or be empty. 

spanned record. A logical record whose length exceeds 
control interval length, and as a result, crosses, or spans, 
one or more control interval boundaries within a single 
control area. 

SRB. Service request block. A system control block 
used for dispatching tasks. 

step catalog. A catalog made available for a step by 
means of the S l EPCAT DD statement. 

terminal monitor program. In TSO, a program that 
accepts and interprets commands from the terminal, and 
causes the appropriate command processors to be 
scheduled and executed. 

time sharing option. An optional configuration of the 
operating system that provides conversational time 
sharing from remote stations. 

TMP. {See terminal monitor program.) 



transaction ID. A number associated with each of 
several request parameter lists that define requests 
belonging to the same data transaction. 

TSO. {See time sharing option.) 

update number. For a spanned record, a binary 
number in the second RDF of a record segment that 
indicates how many times the segments of a spanned 
record should be equal. An inequality indicates a 
possible error. 

upgrade set. All the alternate indexes that VSAM has 
been instructed to update whenever there is a change to 
the data component of the base cluster. 

user buflcring. The use of a work area in the processing 
program's address space for an I/O buffer; VSAM 
transmits the contents of a control interval between the 
work area and direct access storage without 
intermediary buffering. 

user catalog. An optional catalog used in the same way 
as the master catalog and pointed to by the master 
catalog. It also lessens the contention for the master 
catalog and facilitates volume portability. 

vertical pointer. A pointer in an index record of a given 
level that gives the location of an index record in the 
next lower level or the location of a control interval in 
the data set controlled by the index. 

virtual storage access method. An access method for 
direct or sequential processing of fixed and 
variable-length records on direct access devices. The 
records in a VSAM data set or file can be organized in 
logical sequence by a key field (key sequence), in the 
physical sequence in which they are written on the data 
set or file (entry sequence), or by relative record 
number. 

I virtual telecommunications access method. A set of 
I programs that control communication between terminals 
I and application programs running under VSE, OS VSl, 
I andOS/VS2. 

VSAM. {See virtual storage access method.) 

VSAM resource pool. A virtual storage area that is 
used to share I/O buffers, I/O-rclated control blocks, 
and channel programs among VSAM data sets. A 
resource pool is local or global; it serves tasks in one 
partition or address space or tasks in all address spaces 
in the system. 

VSAM shared information. Blocks that are used for 
cross-system sharing. 

VSI. {See VSAM shared information.) 
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I VTAM. {See virtual telecommunications access 
I method.) 
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reason codes from OPEN macro 2 
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at assembly time 34 
generating at execution time 69 
testing 1 54 
ACB macro 43 

example using local shared resources and 31 -bit 
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format 34 

generate an access method control block at assembly 
time 

summary 159 
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ACB parameter 

in t lLLDS parameter 142 
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in MODCB macro 100 

in RPL macro 126 

in SHOWCB macro 133 

in TESTCB macro 146 
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ACQKANGE macro 44 

CNVI AD macro 57 
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ACBLCN parameter 

in FIELDS parameter 134 
access method control block 
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ACQ RANGE macro 

format 44 

summary 1 59 
ACl lON* REFRESH parameter 

in VERIFY macro 155 
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addressed-sequential addition example 1 19 
address constant 

A-type 33. 182 
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address list 

in parameter lists ofGENCB, MODCB, SHOWCB. 
and TESTCB macros 183 
addressed-sequential deletion 

example 64 
ADR subparameter 

in MACRF parameter of the ACB macro 38 

in OPTCD parameter of RPL macro 428 
A IX option 



in MACRF parameter of the ACB macro 39 
AIXFLAG parameter 

in TESTCB macro 153 
AIXPC parameter 

in FIELDS parameter 142 

in TESTCB macro 153 
ALL subparameter 

in WRTBFR macro 156 
alternate index 

providing buffers for shared resources 46 
AM parameter 

in ACB macro 34 

in EXLST macro 66 

in GENCB macro 70, 76, 81 

in RPL macro 126 
AMODE31 subparameter 

removal from the ACB macro 34 

removal from the GENCB macro 69 

removal from the MODCB macro 100 
ARD subparameter 

in OP rCD parameter of RPL macro 129 
AREA parameter 

in FIELDS parameter 142 

in GENCB macro 81 

in RPL macro 126 

in SIIOWCB macro 133, 139, 141 
AREA subparameter 

SCIIBFR macro 132 
AREA L EN parameter 

in FIELDS parameter 142 

in GirNCB macro 81 

in RPL macro 127 
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PUTIX macro 125 

SCIIBFR macro 132 
ARG parameter 

in FIELDS parameter 142 

in GENCB macro 81 

in RPL macro 127 
ARG subparameter 

ACQ RANGE macro 44 

CNVl AD macro 57 

GETIX macro 97 

MNTACQ macro 98 

MRKBFR macro 106 

SCIIBFR macro 132 
assembly time 

generate a request parameter list, summary 165 

generate ACB 34 

generate an access method control block, 
summary 159 

generate an exit list 66 

generate an request parameter list 126 

generate exit list, summary 161 
ASY subparameter 

in OPTCD parameter of RPL macro 129 
asynchronous request 

canceling 62 
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in MNTACQ macro 99 

return codes 14 
ATRB parameter 

in TESTCB macro 147 
AVSPAC parameter 

in FIELDS parameter 135 
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BFRFND parameter 

in FIELDS parameter 135 
BFRNO parameter 

SCIIBFR macro 132 
BLDVRP macro 

execute form 174 

format 46 

list form 174 

obtaining resource pool above 16M example 49 

request separate data and index pools example SO 

return codes 30 

summary 160 
BLK parameter 

in GENCB macro 70, 76, 81 
brackets, in notation convention vii 
BSTRNO parameter 

in ACB macro 34 

in FIELDS parameter 134 

in GENCB macro 70 
bulTers 

above 1 6 megabytes 40 
B U F F E RS parameter 

BLDVRP macro 46 
BUFFERSPACE parameter 

in GENCB macro 70 
B U F N D parameter 

in ACB macro 35 

in FIELDS parameter 134 

in GENCB macro 70 
BUFND subparameter 

BUFSP parameter in ACB macro 35 
BUFNI parameter 

in ACB macro 35 

in FIELDS parameter 135 

in GENCB macro 70 
BUFNI subparameter 

BUFSP parameter in ACB macro 35 
BUFNO parameter 

in F I E L DS parameter 1 35 
BUFRDS parameter 

in FIELDS parameter 135 
BUFSP parameter 

ACB macro 35 

in FIELDS parameter 135 

in GENCB macro 70 
building 

parameter lists for GENCB, MODCB, SMOWCB, 
and TESTCB macros 

format of parameter lists 185 



macros used 185 
building header and clement entries 185 
building parameter list for GENCB macro 

coding example 185 
building parameter lists 183 
BWD subparameter 

in OPTCD parameter of RPL macro 129 
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capitalizing, in notation convention vii 
CATALOG parameter 

in ACB macro 36 

in GENCB macro 71 

in TESTCB macro 147 
CFX subparameter 

in MACRF parameter of the ACB macro 38 
chaining request parameter lists 

example in GENCB macro 84 

in GET macro 96 

not allowed with 
WR'IBFR 156 
CHECK macro 54 

format 51 

suspend processing 
summary 160 

with the. WR:i:aFEta>acr» 1S& 
checking return codes 

after a synchronous request 52 

allcir an asynchronous request 51 
CI IK subparameter 

in WRTBFR macro 157 
CINV parameter 

in FIELDS parameter 135 
CLOSE macro 

disconnecting program and data 
summary 160 

example 56 

format 55 

return codes 6 

use of SI lOWCB macro 6 
closing a data set 

writing buffers 156 
CNV subparameter 

in MACIRF parameter of tlic ACB macro 38 

in OPfCD parameter of RPL macro 128 
CNVTAD macro 

format 57 

summary 160 
component code 13 

from alternate index upgrade requests 14 
connecting program and data (OPEN macro) 107 
control block manipulation macro 

return codes and reason codes 10 
control information 

parameter lists of G ENCB, MODCB, S I lOWCB, 
and TESTCB macros 
address list 1 83 



198 MVS/XA VSAM Administration: Macro Instruction Reference 



element entry 183 
header entry 183 
COPIES parameter 

in GENCB macro 71, 77, 81 
CRA parameter 

in ACB macro 36 
in GENCB macro 72 
in TESTCB macro 147 




DATA option 

BLDVRP macro 48 
data set attributes 

testing in TESTCB macro example 148 
DDN subparameter 

in MACRF parameter of the ACB macro 38 
DDNAME parameter 

in ACB macro 37 

in FIELDS parameter 13S 

in GENCB macro 72 
deferring write requests 3 
deleting a record 

addressed -sequential deletion 64 

ERASE macro 63 

key-direct deletion 63 
DPR subparameter 

in MACRF parameter of the ACB macro 38 
DIN VALID subparameter 

in MRKBFR macro 106 
DIR subparameter 

in MACRF parameter of the ACB macro 38 

in OPrCD parameter of RPL macro 1 28 
direct processing 

reason code positioning state 2S 
disconnecting your program 

CLOSE macro 55 
DLVRP macro 

example 60 

execute form 175 

format 59 

return codes 31 

summary 160 
DRBA subparameter 

in WRTBFR macro 157 
DS subparameter 

in WRTBFR macro 157 
DSN subparameter 

in MACRF parameter of the ACB macro 38 



S 

ECB parameter 

in FIELDS parameter 142 

in GENCB macro 82 

in RPL macro 127 
ECB subparameter 

CNVI AD macro 58 

MRKBFR macro 106 

SCHBFR macro 132 
element entry 

in parameter lists of GENCB, MODCB, SHOWCB, 
and TESTCB macros 183 
coding example 185 
illustration 185 
ellipses, in notation convention vii 
end-of-volume 

return codes 31 
EN DRBA parameter 

in FIELDS parameter 136 
ENDREQ macro 

example 61 

format 61 

terminating a request 
summary 1 60 

used with WRl Bl R macro 1 56 
entry 

element, in parameter lists of GENCB, MODCB, 
SHOWCB, and TESTCB macros 1 83 

header, in parameter lists of GENCB, MODCB, 
SHOWCB. and TESTCB macros 1 83 
£ntry-s£qucoced data set 

used in ACQ RANGE macro 44 
EODAD parameter 

in EXLST macro 66 

in GENCB macro 76 

in SHOWCB macro 139 

in TESTCB macro 150 
ERASE macro 

deleting a record 
summary 160 

format 63 
ERASE processing 63 
ERET parameter 

in TESTCB macro 146, 150. 152 
error field of the ACB 

reason codes from OPEN macro 2 
ERROR parameter 

in FIELDS parameter 135 
CSDS parameter 

in TESTCB macro 146 
event control block 

used in ACQRANGE macro 45 
example 

addition of records, PUT macro 1 19 
addressed -sequential deletion, ERASE macro 64 
addressed-sequcntial retrieval, GET macro 89 
addressed-sequential update, PUT macro 123 
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check return code after asynchronous request, 

CHECK macro 51 
checking return code after synchronous request, 

CHECK macro 52 
close data set with parameter list above I6M, 

CLOSE macro 56 
connect LSR pool and run in 31 -bit addressing 

mode, ACB macro 43 
delete LSR pool, DLVRP macro 60 
display an ACB, SI lOWCB macro 1 37 
display an exit list address in the ACB, SHOWCB 

macro 1 38 
display exit list length, SI lOWCB macro 140 
display physical error message, SHOWCB 

macro 144 

generate an access method control block, GENCB 

macro 75 
generate an exit list, GENCB macro 78 
generate an RPL at assembly time, RPL 

macro 131 

generate request parameter list, GENCB macro 85 

identify data set, ACB macro 42 

identify exit routines, EXLST macro 67 

keyed -direct deletion, ERASE macro 63 

keyed-direct insertion, PUT macro 118 

keyed direct update, PUT macro 121 

keyed -sequential insertion, PUT macro 111, 115 

keyed-sequential retrieval (backward), GET 

macro 87 
keyed-seqecntiat retrieve, GET masra 86- 
keyed-sequential update, PUT macro 1 20 
loading a relative record data set, PUT macro 113 
marking records inactive, PUT macro 124 
modify a request parameter list, MODCB 

macro 105 
modify an exit list, MODCB macro 103 
modify name of exit list in ACB, MODCB 

macro 101 
obtain LSR above 16M, BLDVRP macro 49 
obtaining resource pool above 16M, BLDVRP 

macro 49 

open macro with parameter list above 16M, OPEN 

macro 108 
open two data sets, OPEN macro 108 
overlay processing, CHECK macro 52 
position, POINT macro 109 
recording RBAs when loading, PUT macro 112 
release positioning, ENDREQ macro 61 
request separate data and index pools, BLDVRP 

macro 50 
request separate data/index resource pools, 

BLDVRP macro 50 
retrieving a keyed-direct record, GET macro 92 
retrieving a relative record sequentially, GET 

macro 91 
retrieving an addressed-direct record, GET 

macro 93 
retrieving direa to sequential record, GET 

macro 94 
ski -sequential retrieval, GET macro 87 
skip-sequential insertion, PUT macro 1 1 6 



suspend many record request, CHECK macro 53 

test a request parameter list, TESTCB macro 154 

test for data set attributes, TESTCB macro 148 

use a branch table, TESTCB macro 151 
example of generate, list, execute forms in reentrant 
environment 179 
execute form 

BLDVRP macro 174 

DLVRP macro 175 

GENCB macro 175 

MODCB macro 176 

SHOWCB macro 177 

TESTCB macro 178 

use of 178 
execute-form keyword 173 
execution time 

generate a request parameter list, summary 162 

generate an ACB 69 

generate an access method control block 161 
generate an exit list, summary 1 62 
generate exit list 76 
generate request parameter list 80 
exit list 

address displayed in SHOWCB macro 
example 138 

fields displayed in SHOWCB macro 139 

generating at execution time 76 

generating in EXLS T macro 66 

length displayed in SHOWCB macro example 140 
EXLLEN paxam&se 

in SHOWCB macro 139 

in TESTCB macro 151 
EXLST macro 

example 67 

format 66 

generate exit list at assembly time 
summary 161 
EXLST parameter 
in ACB macro 37 
in FIELDS parameter 135 
in GENCB macro 72 
in MODCB macro 102 
in SHOWCB macro 139 
in TESTCB macro 150 



0 

FDBK parameter 

in FIELDS parameter 142 
feedback word in the RPL 13 
FIELDS parameter 

in SI lOWCB macro 134, 1 39, 142 
FIX parameter 

BLDVRP macro 46 
FKS subparameter 

in OPTCD parameter of RPL macro 130 
format 

ACB macro 34 
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ACQRANGE macro 44 
BLDVRP macro 46 
CHECK macro 51 
CLOSE macro 55 
CNVTAD macro 57 
DLVRP macro 59 
ENDREQ macro 61 
ERASE macro 63 
execute form 

of BLDVRP macro 174 

of DLVRP macro 175 
EXLS r macro 66 
GENCB macro 69 
G ET macro 86 
GETIX macro 97 
list form 

of BLDVRP macro 174 
MNTACQ macro 98 
MODCB macro 100 
MRKBER macro 106 
OPEN macro 107 

parameter lists of GENCB, MODCB, SliOWCB, 

and TES'I CB macros 
address list 185 
element entry 185 
header entry 185 

POINT-roacro 109 

PU T macb 1 1 1 

PUnX macro 125 

RPL macro 126 

sen BFR macro 132 

SIIOWCB macro 133 

TES rCB macro 145,150 

Vi-RU Y macro 155 

VV RIB PR macro 156 
format of the parameter lists 1 83 
I'S parameter 

in FIELDS parameter 136 
FTNCD parameter 

in FIELDS parameter 142 

in TESTCB macro 153 
FVVD subparametcr 

in OPTCD parameter of RPL macro 129 
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GENCB macro 

execute form 1 75 

with parameter lists built by user 183, 185 
format 69 

generate a request parameter list at execution time 

summary 162 
generate an access method* control block at 

execution time 
summary 161 



generate an exit list at execution time 
summary 1 62 

generate form 176 

reentrant example 1 79 

generating a request parameter list 80 

generating a request parameter list example 85 

generating an access method control block 69 

generating an access method control block 
example 75 

generaUng an exit list 76 

generating an exit list example 78 

inconsistent operand error 3 

linking to VSAM directly 187 

list form 175 

operand notation 181 

reason codes 10 

return codes 10 
generate form 

GENCB macro 176 

MODCB macro 176 

SIIOWCB macro 177 

TESTCB macro 178 

use of 178 
generatc-form keyword 173 
generating a request parameter list 

GENCB macro 80 

RPL macro 126 
generating an access method control block (GENCB 

macro) 69 
generating an exit list 

at assembly time 66 

GENCB macro 76 
GILT macro 

format %6 

retrieving a direct to sequential record example 94 
retrieving a keyed-direct record 92 
retrieving a keyed -sequential record (backward) 
example 

backward 87 
retrieving a record 

summary 1 62 
retrieving a relative record example 91 
retricNing a skip-sequential record, example 87 
retrieving an addressed -direct record example 93 
retrieving an addressed-sequential record 

example 89 
retrieving keyed -sequential record example 

forward 86 
GETIX macro 
format 97 

rctrioing an index record 
summary 163 
GSR option 

BLDVRP macro 48 

in MACRF parameter of the ACB macro 39 
GSR subparameter 
DLVRP macro 59 
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HALCRBA parameter 

in FIELDS parameter 136 

header entry 

in parameter lists of GENCB, MODCB, SHOWCB, 
and TKSTCB macros 
coding example 185 
iltustration 185 
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ICI subparameter 

in MACRF parameter of the ACB macro 38 
lOAELEM macro 185 
! D AG ENC macro 185 
IDAMODC macro 185 
I DAS I low macro 185 
IDATESTmacro 185 
IN subparameter 

in MACRF parameter of the ACB macro 38 
index 

retrieval (GETIX macro) 97 

storing. (PUTIXmacroX 125 
INDEX opUon 

BLDVRP macro 48 
indirect address for S-type address constant 33 
indirect S-lype address constant 69 
inserting records 

keyed-direct 118 

keyed-sequential 111,115 
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lO parameter 

in TESTCB macro 153 
lOPlD parameter 

in EXLST macro 66 
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JRNAD parameter 

in EXLST macro 67 
in GENCB macro 77 
in SIIOVVCB macro 140 
in l ES rCB macro 150 



KEQ subparameter 

in O PTCD parameter of RPL macro 1 29 
KEY subparameter 

in MACRF parameter of the ACB macro 38 

in OrrCD parameter of RPL macro 1 28 
key-direct deletion 

example 63 
key-sequenccd data set 

used in ACQRANGE macro 44 
KEYLEN parameter 

BLDVRP macro 47 

in FIELDS parameter 136, 143 

in GENCB macro 82 

in RPL macro 127 
keywords 

execute form 1 73 

generate form 173 

list form 1 72 
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in OP r(3D parameter of RPL macro 130 
KSDS parameter 

in TESTCB macro 146 
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LDS parameter 

in TESTCB macro 146 
LENGTH parameter 

in GENCB macro 72, 77, 82 

in SlIOWCB macro 133,139,141 
LERAD parameter 

in EXLST macro 67 

in GENCB macro 77 

in SIIOWCB macro 140 

in TESTCB macro ISO 
linear data set 

error in VERIFY macro 155 

logical error reason codes 23 
linking to VS AM direcUy 187 
list form 

BLDVRP macro 174 

GENCB macro 175 

MODCB macro 176 

SIIOWCB macro 177 

TESTCB macro 177 

use of 178 
list-form keyword 172 
list, execute, generate formats 1 74 
list, execute, generate forms of macros 171 
list, parameter 

ofGENCB, MODCB. SIIOWCB, and TESTCB 
macros 183 
LOC parameter 

in GENCB macro 72. 77, 82 
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removal from the BLDVRP macro 47 
LOC subparameter 

in OPTCD parameter of RPL macro 1 30 
local shared resources 

ACB example 43 
locate mode 

with control interval access 
with shared resources 132 
lower case, in notation convention vii 
l.RD subparameter 

in OPI CD parameter of RPL macro 129 
LRECL parameter 

in FIELDS parameter 136 
LRU subparameter 

in WRTBFR macro 157 
LSR option 

BLDVRP macro 48 

DLVRP macro 59 

in MACRF parameter of the ACB macro 39 
LSR pool 

example in BLDVRP macro 50 
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MACRF parameter 

in ACB macro 37 

in GENCB macro 72 

in TESTCB macro 147 
macro instruction return codes and reason codes 1 
macros 

descriptions 1 

summary of 
MA RE A parameter 

in ACB macro 40 

in FIELDS parameter 135 

in GENCB macro 73 
MARK parameter 

in MRKBFR macro 106 
marking records inactive 124 
message area 

header information 8 

message list 9 

OPEN/CLOSE 7 

provided by VSAM 7 
ML EN parameter 

in ACB macro 40 

in FIELDS parameter 135 

in GENCB macro 73 
MNTACQ macro 

format 98 

summary 163 
MODCB macro 

example 101 

execute form 176 

reentrant example 180 

with parameter lists built by user 183 

format 100 

generate form 176 



linking to VSAM directly 187 
list form 176 

modify a request parameter list example 105 
modify an exit list example 103 
modifying a request parameter list 104 

summary 164 
modifying an ACB 100 

summary 163 
modifying an exit list 
format 102 
summary 163 
operand notation 181 
reason codes 10 
remote-list form 

reentrant example 179 
return codes 10 
MODE option 

BLDVRP macro 48 
MODE parameter 
DLVRP macro 59 
in CLOSE macro 55 
in OPEN macro 107 
modifying and displaying the RECLEN field of an RPL 

direcdy 188 
move mode of control interval access 

with shared resources 132 
MRKBFR macro 
format 106 
invalidating a buffer 
parameters for 106 
reason codes 106 
summary 1 64 
MSG A RE A parameter 

in FIELDS j)aramcter 143 
in GENCB macro 82 
in RPL macro 127 
MSGLEN parameter 

in FIELDS parameter 143 
Hn GENCB macro 82 
in RPL macro 127 
MVE subparameter 

in OPTCD parameter of RPL macro 1 30 
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NCI subparameter 

in MACRF parameter of the ACB macro 38 
NCIS parameter 

in FIELDS parameter 136 
NDELR parameter 

in FIELDS parameter 136 
NDF subparameter 

in MACRF parameter of the ACB macro 38 
NEXCP parameter 

in FIELDS parameter 136 
NEXT parameter 

in FIELDS parameter 136 
NFX subparameter 
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in MACRF parameter of the ACB macro 38 
NINSR parameter 

in F I E L f )S parameter 1 36 
NIS subparamcter 

in MACRF parameter of the ACB macro 39 
NIXL parameter 

in FIEI.DS parameter 136 
NLOGR parameter 

in F 1 1: 1 . DS parameter 1 36 
NO subparamcter, in CATALOG parameter 

in ACB macro 36 

in GFNCB macro 71 

in TFSTCB macro 147 

restriction 36, 71 
N R ET R parameter 

in FIELDS parameter 136 
NRM option 

in MACRF parameter of the ACB macro 39 
NRS option 

in MACRF parameter of the ACB macro 39 
NSP subparamcter 

in OPrCD parameter of RPL macro 129 
NSR option 

in MAC'RI' parameter of the ACB macro 39 
NSSS parameter 

in FIELDS parameter 136 
NUB option 

in MACRF parameter of the ACB macro 39 
NUIVV parameter 

in FIELDS parameter 137 
N U P subparamcter 

in O P rc D parameter of R PL macro 1 29 
NUPDR parameter 

in FIELDS parameter 137 
NWAITX subparamcter 

in OPTCD parameter of RPL macro 130 
NXTRPL parameter 

in FIELDS parameter 143 

in GENCB macro 83 
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OBJECr parameter 

in SIIOWCB macro 134 

in TESTCB macro 146 
OF LAGS parameter 

in TESTCB macro 147 
OPEN macro 

connecting program and data 
summary 164 

format 107 

open two data sets example 108 

parameter list above 16M example 108 

reason codes 2 

use of SHOWCB macro 2 
use of VERIFY command 2 

return codes I 



shared resources 
reason codes 3 
OPEN/CLOSE message area for multiple 

reason/warning messages 7 
opening a data set 

for processing 107 
OPENOBJ parameter 

in TESTCB macro 148 
operand notation 

GENCB 181 

MODCB 181 

SHOWCB 181 

TESTCB 181 
operands 

optional 174 

required 174 
operands with GENCB, MODCB, SIIOWCB, 
TESTCB 181 
OPTCD parameter 

in GENCB macro 83 

in RPL macro 128 

in TESTCB macro 153 
OPrCD subparamcter 

ACQ RANG I- macro 44 

GETIX macro 97 

in RPL macro 130 

MNTACQ macro 98 

PU Tlx macro 125 

SCI I BFR macro 132 
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OUT subparamcter 

in MACRF parameter of the ACB macro 39 

in MRKBFR macro 106 
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parameter list 

of GENCB, MODCB, SHOWCB, and TES1 CB 
macros 183 
passing control directly to VSAM 187 
PASSWD parameter 

in ACB macro 40 

in FIELDS parameter 135 

in GENCB macro 73 
physical error analysis 

with control interval access 26 
physical error message 

displayed in SIIOWCB macro example 144 

format 30 

RBA field 26 
POINT macro 

format 109 

position example 109 

positioning for access 
summary 164 
positioning 

following logical errors 24 
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of reason codes 25 
positioning for access (POINT macro) 109 
PUT macro 

addressed -sequential update example 123 

format 1 1 1 

k^ed-direct insertion example 118 
keyed -direct update example 121 
keyed -sequential insertion example 111, 115 
keyed -sequential update example 120 
loading a relative record data set 113 
marking records inactive example 124 
recording RBAs when loading example 112 
skip-sequential insertion example 1 1 6 
storing a record 

summary 164 
PUTIX macro 
format 125 
storing an index record 

summary 165 



R 



RBA field 

in physical error message 26 
RBA parameter 

in I'lKLOS parameter 143 
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CNV1 AD macro 58 
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reason codes 

from OI*EN macro 2 

from request macros (GF.T, PUT, etc.) 

physical errors, control interval access 26 
in control block manipulation macros 10 
in GI:NCB macro 10 
in MODCB macro 10 
in SIIOWCB macro 10 
in TESTCB macro 10 
logical errors 17 
physical errors 26 
positioning state 25 

request parameter list feedback area 13, 15 
shared resources from OPEN macro 3 
successful request 15 

use of VERI FY command in OPEN macro 2 
RECLEN field (record length) of an RPL 
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